@lukoweb/apitogo 0.2.49 → 0.2.51

package/src/config/v2/wrapper.ts

@@ -23,6 +23,7 @@ import {
 import { type PortalProfile, portalProfile } from "./portal-profile.js";
 import { protectedRoutesFor } from "./protected-routes.js";
 import type { ResolvedConfigV2 } from "./resolve.js";
+import { findTsxPages, TSX_PAGE_ELEMENT_PREFIX } from "./tsx-pages.js";
 
 export const WRAPPER_FILE = "apitogo.config.tsx";
 
@@ -76,6 +77,10 @@ export type PortalPlan = {
     billing?: string;
     /** Where the account pages link to: only places this portal has (hosted docs, an external docs site, the API page). */
     links?: { docs?: string; api?: string };
+    /** The header API users send their key in, from the gateway entry of services.json (API-120). */
+    keyHeader?: string;
+    /** The gateway's address, for code samples on the portal's pages. */
+    gatewayBaseUrl?: string;
   };
   /** Account pages. */
   userPanel: boolean;
@@ -258,6 +263,10 @@ export function planPortal(
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
+      ...(gateway?.keyHeaderName ? { keyHeader: gateway.keyHeaderName } : {}),
+      ...(gateway?.baseUrl && serviceReady(gateway)
+        ? { gatewayBaseUrl: gateway.baseUrl }
+        : {}),
       links: {
         // Hosted docs are linked once their pages are known (see `buildPortalWorkspace`): there is no page to
         // name before that, and a guessed one was a 404 on every portal whose first page is not called `introduction`.
@@ -424,8 +433,17 @@ function authenticationFor(plan: PortalPlan): Record<string, unknown> {
 export const PREVIEW_BANNER_MESSAGE =
   "Preview mode: sign in with demo@apitogo.local / password to try the console. Run `apitogo deploy` for the real services.";
 
-/** The wrapper source. Imports exist only for what the plan registers. */
-export function renderWrapper(plan: PortalPlan): string {
+/** A React docs page the wrapper imports: `importPath` is relative to the wrapper, through the `content` link. */
+export type WrapperPage = { id: string; importPath: string };
+
+/**
+ * The wrapper source. Imports exist only for what the plan registers. React docs pages are imported here and put in
+ * place of their sidebar placeholders, since the site config is JSON and cannot hold a component.
+ */
+export function renderWrapper(
+  plan: PortalPlan,
+  pages: readonly WrapperPage[] = [],
+): string {
   const imports = [
     'import { buildApitogoConfig } from "@lukoweb/apitogo/build-config";',
     ...(plan.plansPlugin
@@ -433,12 +451,41 @@ export function renderWrapper(plan: PortalPlan): string {
           'import { devPortalBillingPlugin } from "@lukoweb/apitogo-plugin-dev-portal-billing";',
         ]
       : []),
+    ...(pages.length > 0 ? ['import { createElement } from "react";'] : []),
+    ...pages.map(
+      (page, index) =>
+        `import TsxPage${index} from ${JSON.stringify(page.importPath)};`,
+    ),
     `import siteConfig from "./${SITE_CONFIG_FILE}";`,
   ];
   const plugins = plan.plansPlugin
     ? `[devPortalBillingPlugin(${JSON.stringify(plan.plansPlugin)})]`
     : "[]";
 
+  const pageLines =
+    pages.length === 0
+      ? []
+      : [
+          "",
+          "// React docs pages: each sidebar placeholder becomes the page's component.",
+          "const tsxPages: Record<string, any> = {",
+          ...pages.map(
+            (page, index) => `  ${JSON.stringify(page.id)}: TsxPage${index},`,
+          ),
+          "};",
+          "const withTsxPages = (items: any[]): any[] =>",
+          "  items.map((item) => {",
+          '    if (item === null || typeof item !== "object") return item;',
+          "    const page =",
+          '      typeof item.element === "string" ? tsxPages[item.element] : undefined;',
+          "    return {",
+          "      ...item,",
+          "      ...(page ? { element: createElement(page) } : {}),",
+          "      ...(Array.isArray(item.items) ? { items: withTsxPages(item.items) } : {}),",
+          "    };",
+          "  });",
+        ];
+
   return [
     "// Generated by apitogo from apitogo.config.json and services.json. Do not edit: it is rewritten on every build.",
     ...(plan.preview
@@ -447,11 +494,28 @@ export function renderWrapper(plan: PortalPlan): string {
         ]
       : []),
     ...imports,
+    ...pageLines,
     "",
-    "export default buildApitogoConfig({",
-    "  ...siteConfig,",
-    `  plugins: ${plugins},`,
-    "});",
+    // The components go in after buildApitogoConfig: it copies the config with structuredClone, which cannot copy a
+    // React element.
+    ...(pages.length > 0
+      ? [
+          "const config = buildApitogoConfig({",
+          "  ...siteConfig,",
+          `  plugins: ${plugins},`,
+          "});",
+          "",
+          "export default {",
+          "  ...config,",
+          "  navigation: withTsxPages((config as any).navigation ?? []),",
+          "};",
+        ]
+      : [
+          "export default buildApitogoConfig({",
+          "  ...siteConfig,",
+          `  plugins: ${plugins},`,
+          "});",
+        ]),
     "",
   ].join("\n");
 }
@@ -580,11 +644,27 @@ export async function preparePortal(
       });
     }
   }
-  const hostedDocRoutes = plan.docs
+  const markdownRoutes = plan.docs
     ? await docRoutes(profile.docs.content, {
         includeDrafts: mode === "development",
       })
     : [];
+  // React pages next to the Markdown ones. A Markdown page wins over a React page at the same address.
+  const tsxPages = plan.docs
+    ? (await findTsxPages(profile.docs.content)).filter(
+        (page) => !markdownRoutes.includes(page.route),
+      )
+    : [];
+  const wrapperPages: WrapperPage[] = tsxPages.map((page, index) => ({
+    id: `${TSX_PAGE_ELEMENT_PREFIX}${index}`,
+    importPath: `./${CONTENT_LINK}/${path
+      .relative(resolved.configDir, page.file)
+      .split(path.sep)
+      .join("/")}`,
+  }));
+  const hostedDocRoutes = [
+    ...new Set([...markdownRoutes, ...tsxPages.map((page) => page.route)]),
+  ].sort();
   // The account pages' "Documentation" link goes to a page the portal really has, or is left out.
   if (plan.plansPlugin && plan.docs) {
     const landing = hostedDocRoutes.some(
@@ -617,7 +697,14 @@ export async function preparePortal(
     await readTheme(resolved),
     {
       redirects: home ? [home] : [],
-      docsNavigation: docsNavigation(hostedDocRoutes),
+      docsNavigation: docsNavigation(
+        markdownRoutes,
+        tsxPages.map((page, index) => ({
+          route: page.route,
+          label: page.label,
+          element: wrapperPages[index]?.id ?? "",
+        })),
+      ),
       docsPath: pickLandingRoute(hostedDocRoutes),
       demoPlans:
         plan.demo && plan.plansPlugin
@@ -633,7 +720,7 @@ export async function preparePortal(
       }),
     },
   );
-  const wrapper = renderWrapper(plan);
+  const wrapper = renderWrapper(plan, wrapperPages);
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
   if (options.write !== false) {
     await mkdir(path.dirname(wrapperPath), { recursive: true });

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -1,135 +1,147 @@
-import { HTTPSnippet } from "@zudoku/httpsnippet";
-import type { OperationsFragmentFragment } from "../graphql/graphql.js";
-
-const toFormDataParams = (text?: string) => {
-  const stringify = (v: unknown) =>
-    typeof v === "string" ? v : JSON.stringify(v);
-
-  try {
-    const obj = text && JSON.parse(text);
-    if (typeof obj !== "object" || !obj) return [];
-
-    return Object.entries(obj).flatMap(([name, value]) => {
-      const values = Array.isArray(value) ? value : [value];
-      return values.map((v) => ({ name, value: stringify(v) }));
-    });
-  } catch {
-    return [];
-  }
-};
-
-export const createHttpSnippet = ({
-  operation,
-  selectedServer,
-  exampleBody,
-}: {
-  operation: OperationsFragmentFragment;
-  selectedServer: string;
-  exampleBody: {
-    mimeType: string;
-    text?: string;
-  };
-}) => {
-  const isMultipart =
-    exampleBody.mimeType === "multipart/form-data" ||
-    exampleBody.mimeType === "application/x-www-form-urlencoded";
-
-  const postData = isMultipart
-    ? {
-        mimeType: exampleBody.mimeType,
-        params: toFormDataParams(exampleBody.text),
-      }
-    : exampleBody;
-
-  return new HTTPSnippet({
-    method: operation.method.toUpperCase(),
-    url:
-      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
-    postData,
-    headers: [
-      ...(exampleBody.text
-        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
-        : []),
-      ...(operation.parameters
-        ?.filter((p) => p.in === "header" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? []),
-    ],
-    queryString:
-      operation.parameters
-        ?.filter((p) => p.in === "query" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? [],
-    httpVersion: "",
-    cookies: [],
-    headersSize: 0,
-    bodySize: 0,
-  });
-};
-
-export const getConverted = (snippet: HTTPSnippet, option: string) => {
-  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
-  let converted: any;
-  switch (option) {
-    case "shell":
-      converted = snippet.convert("shell", "curl");
-      break;
-    case "js":
-      converted = snippet.convert("javascript", "fetch");
-      break;
-    case "python":
-      converted = snippet.convert("python", "requests");
-      break;
-    case "java":
-      converted = snippet.convert("java", "okhttp");
-      break;
-    case "go":
-      converted = snippet.convert("go", "native");
-      break;
-    case "csharp":
-      converted = snippet.convert("csharp", "httpclient");
-      break;
-    case "kotlin":
-      converted = snippet.convert("kotlin", "okhttp");
-      break;
-    case "objc":
-      converted = snippet.convert("objc", "nsurlsession");
-      break;
-    case "php":
-      converted = snippet.convert("php", "http2");
-      break;
-    case "ruby":
-      converted = snippet.convert("ruby");
-      break;
-    case "swift":
-      converted = snippet.convert("swift");
-      break;
-    default:
-      converted = snippet.convert("shell");
-      break;
-  }
-
-  return converted ? converted[0] : "";
-};
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+/** Operation extension with the header a key goes in (same name as `KEY_HEADER_EXTENSION` in the CLI's config). */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
+
+/** What a code sample shows where the visitor's key goes. */
+export const KEY_PLACEHOLDER = "YOUR_API_KEY";
+
+const toFormDataParams = (text?: string) => {
+  const stringify = (v: unknown) =>
+    typeof v === "string" ? v : JSON.stringify(v);
+
+  try {
+    const obj = text && JSON.parse(text);
+    if (typeof obj !== "object" || !obj) return [];
+
+    return Object.entries(obj).flatMap(([name, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.map((v) => ({ name, value: stringify(v) }));
+    });
+  } catch {
+    return [];
+  }
+};
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  const isMultipart =
+    exampleBody.mimeType === "multipart/form-data" ||
+    exampleBody.mimeType === "application/x-www-form-urlencoded";
+
+  const postData = isMultipart
+    ? {
+        mimeType: exampleBody.mimeType,
+        params: toFormDataParams(exampleBody.text),
+      }
+    : exampleBody;
+
+  const keyHeader = operation.extensions?.[KEY_HEADER_EXTENSION];
+
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    postData,
+    headers: [
+      // The gateway's key header, on operations that need a key (set by the portal build, API-120).
+      ...(typeof keyHeader === "string" && keyHeader
+        ? [{ name: keyHeader, value: KEY_PLACEHOLDER }]
+        : []),
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  let converted: any;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};