@lukoweb/apitogo 0.2.56 → 0.2.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.56",
+  "version": "0.2.57",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/docs-navigation.ts

@@ -24,13 +24,16 @@ const toItems = (
   branch: Branch,
   prefix: string,
   orders: PageOrders,
+  homeTaken = false,
 ): InputNavigationItem[] => {
   // Index first, then the pages' own order, then the usual first pages, then by name (API-125).
   const names = [...branch.pages.keys()].sort((a, b) =>
     comparePages(`/${prefix}${a}`, `/${prefix}${b}`, orders),
   );
   const folders = [...branch.folders.keys()].sort(byName);
-  const folderPath = prefix === "" ? "/" : `/${prefix.slice(0, -1)}`;
+  // With a home page of its own, `/` is the home page and the root index page keeps `/index` (API-129).
+  const folderPath =
+    prefix === "" ? (homeTaken ? "/index" : "/") : `/${prefix.slice(0, -1)}`;
   return [
     ...names.map((name): InputNavigationItem => {
       const page = branch.pages.get(name) as Page;
@@ -58,6 +61,7 @@ const toItems = (
           branch.folders.get(folder) ?? emptyBranch(),
           `${prefix}${folder}/`,
           orders,
+          homeTaken,
         ),
       }),
     ),
@@ -85,6 +89,7 @@ export function docsNavigation(
   routes: string[],
   customPages: readonly CustomDocsPage[] = [],
   orders: PageOrders = new Map(),
+  options: { homeTaken?: boolean } = {},
 ): InputNavigationItem[] {
   const root = emptyBranch();
   for (const route of routes) {
@@ -96,7 +101,7 @@ export function docsNavigation(
     if (page && !branch.pages.has(page))
       branch.pages.set(page, { kind: "custom", ...custom });
   }
-  const items = toItems(root, "", orders);
+  const items = toItems(root, "", orders, options.homeTaken);
   return items.length === 0
     ? []
     : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];

package/src/config/v2/index.ts

@@ -116,6 +116,7 @@ export {
   serviceLabel,
   clearProjectId,
   ServiceEditError,
+  replaceProjectId,
   setProjectId,
   type ServiceEdit,
   type ServiceName,

package/src/config/v2/resolve.ts

@@ -34,6 +34,10 @@ export type ResolvedPortal = {
   theme: string;
   /** Absolute path of the custom home page component, when the portal has one. */
   landing?: string;
+  /** Absolute path of the footer component, when the portal has one (API-129). */
+  footer?: string;
+  /** The header logo, when the portal has one: absolute paths (inside the portal's `public/`) or https URLs (API-129). */
+  logo?: { light: string; dark: string; alt?: string };
   requireAuth: boolean | { exclude: string[] };
   search: "pagefind" | "inkeep" | "none";
 };
@@ -92,6 +96,12 @@ export type ResolvedConfigV2 = {
   plans?: ResolvedPlans;
 };
 
+/** A logo is a file of the portal (served from its `public/` folder) or an https address, which is kept as it is. */
+export const isLogoUrl = (value: string) =>
+  value.toLowerCase().startsWith("https://");
+const logoSource = (configDir: string, value: string) =>
+  isLogoUrl(value) ? value : path.resolve(configDir, value);
+
 /**
  * Applies the documented defaults and makes every path absolute. Defaults for `portal.dir`, `plans.file`
  * and the spec folder derive from `<root>`, so a standalone config can omit them. A section that is present
@@ -146,6 +156,24 @@ export function resolveConfigV2(
       ...(portal.landing
         ? { landing: path.resolve(configDir, portal.landing) }
         : {}),
+      ...(portal.footer
+        ? { footer: path.resolve(configDir, portal.footer) }
+        : {}),
+      ...(portal.logo
+        ? {
+            logo:
+              typeof portal.logo === "string"
+                ? {
+                    light: logoSource(configDir, portal.logo),
+                    dark: logoSource(configDir, portal.logo),
+                  }
+                : {
+                    light: logoSource(configDir, portal.logo.light),
+                    dark: logoSource(configDir, portal.logo.dark),
+                    ...(portal.logo.alt ? { alt: portal.logo.alt } : {}),
+                  },
+          }
+        : {}),
       requireAuth: portal.requireAuth ?? false,
       search: provider === "external" ? "none" : (portal.search ?? "pagefind"),
     };

package/src/config/v2/rules.ts

@@ -4,7 +4,7 @@ import { glob } from "glob";
 import { parse as parseYaml } from "yaml";
 import { billingNeeded, stripeKeySecretName } from "./billing.js";
 import type { ConfigIssue } from "./errors.js";
-import { type ResolvedConfigV2, toGlobPath } from "./resolve.js";
+import { isLogoUrl, type ResolvedConfigV2, toGlobPath } from "./resolve.js";
 import type { ConfigV2 } from "./schema.js";
 import { findTsxPages } from "./tsx-pages.js";
 
@@ -247,6 +247,37 @@ async function portalRules(
     });
   }
 
+  // A missing footer or logo file would fail the build, so check says so first (API-129).
+  if (portal.footer && !(await isFile(portal.footer)))
+    out.error({
+      code: "PORTAL_FILE_MISSING",
+      path: "portal.footer",
+      message: `the file ${path.relative(resolved.configDir, portal.footer)} does not exist.`,
+      hint: "Create it, or remove portal.footer.",
+    });
+  const publicDir = path.join(portal.dir, "public");
+  for (const file of new Set(
+    [portal.logo?.light, portal.logo?.dark].filter(
+      (value): value is string => !!value && !isLogoUrl(value),
+    ),
+  )) {
+    const inside = path.relative(publicDir, file);
+    if (inside.startsWith("..") || path.isAbsolute(inside))
+      out.error({
+        code: "PORTAL_LOGO_OUTSIDE_PUBLIC",
+        path: "portal.logo",
+        message: `the logo ${path.relative(resolved.configDir, file)} is not in the portal's public folder, which is what the site serves.`,
+        hint: `Move it into ${path.relative(resolved.configDir, publicDir)}/, or use an https:// address.`,
+      });
+    else if (!(await isFile(file)))
+      out.error({
+        code: "PORTAL_FILE_MISSING",
+        path: "portal.logo",
+        message: `the file ${path.relative(resolved.configDir, file)} does not exist.`,
+        hint: "Create it, or remove portal.logo.",
+      });
+  }
+
   if (await isFile(portal.theme)) {
     try {
       JSON.parse(await readFile(portal.theme, "utf8"));

package/src/config/v2/schema.ts

@@ -47,6 +47,15 @@ export const PortalSchema = z.strictObject({
   theme: path.optional(),
   /** A custom home page: a React component file that the portal serves at `/`. */
   landing: path.optional(),
+  /** The footer: a React component file shown under every page except the console's (API-129). */
+  footer: path.optional(),
+  /** The logo in the portal header: one image, or one per color scheme (API-129). */
+  logo: z
+    .union([
+      path,
+      z.strictObject({ light: path, dark: path, alt: z.string().optional() }),
+    ])
+    .optional(),
   requireAuth: z
     .union([z.boolean(), z.strictObject({ exclude: pathList })], {
       error: 'must be true, false or { "exclude": ["/route", ...] }',

package/src/config/v2/services.ts

@@ -26,7 +26,7 @@ import { parseConfigV2 } from "./parse.js";
 import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
 import { checkDependencies } from "./rules.js";
 import type { ConfigV2 } from "./schema.js";
-import { starterLandingPage } from "./starter-landing.js";
+import { starterFooter, starterLandingPage } from "./starter-landing.js";
 
 export const SERVICES = ["portal", "gateway", "identity", "plans"] as const;
 export type ServiceName = (typeof SERVICES)[number];
@@ -351,6 +351,29 @@ async function addFile(context: Context, target: string, content: string) {
   else context.files.push({ path: target, content });
 }
 
+/**
+ * The portal's own colors, the same as the built-in theme, so the file changes nothing until it is edited. Any color
+ * of the theme can be added here (see Colors & theme in the docs).
+ */
+export const STARTER_THEME = `${JSON.stringify(
+  {
+    light: {
+      primary: "#0d9488",
+      primaryForeground: "#ffffff",
+      ring: "#0d9488",
+      radius: "0.625rem",
+    },
+    dark: {
+      primary: "#0d9488",
+      primaryForeground: "#ffffff",
+      ring: "#0d9488",
+    },
+  },
+  null,
+  2,
+)}
+`;
+
 async function buildPortal(
   context: Context,
 ): Promise<NonNullable<ConfigV2["portal"]>> {
@@ -410,6 +433,8 @@ async function buildPortal(
           { value: "blank", label: "An empty pages folder" },
         ])) as "starter" | "blank";
       const pages = path.join(resolved.root, "portal", "pages");
+      // Written out, not left to the default, so the config shows where the docs pages live (API-129).
+      content = [`${rel(dir, pages)}/**/*.{md,mdx}`];
       if (template === "blank")
         await addFile(context, path.join(pages, ".gitkeep"), "");
       else if (isFilled(options.template)) {
@@ -437,14 +462,45 @@ async function buildPortal(
         );
         landing = rel(dir, landingFile);
       } else
+        // Not `index.mdx`: an index page answers at `/`, which a home page added later would lose (API-129).
         await addFile(
           context,
-          path.join(pages, "index.mdx"),
+          path.join(pages, "introduction.mdx"),
           starterPage(name),
         );
     }
+    // Always there, so the brand colors are one edit away instead of a docs search (API-129).
+    await addFile(
+      context,
+      path.join(resolved.root, "portal", "theme.json"),
+      STARTER_THEME,
+    );
   }
 
+  // A footer the project owns, like the home page: the config points to it, so it can be changed or removed (API-129).
+  const footerFile = path.join(resolved.root, "portal", "footer", "Footer.tsx");
+  await addFile(
+    context,
+    footerFile,
+    starterFooter({
+      name,
+      links: [
+        ...(isFilled(options.template) && !external
+          ? [{ label: "Documentation", href: "/introduction" }]
+          : []),
+        ...(context.config.gateway
+          ? [{ label: "API Reference", href: "/api" }]
+          : []),
+        ...(context.config.plans && context.config.plans.enabled !== false
+          ? [{ label: "Pricing", href: "/pricing" }]
+          : []),
+        ...(context.config.identity && !o.noConsole
+          ? [{ label: "Sign in", href: "/login" }]
+          : []),
+      ],
+    }),
+  );
+
   return {
     ...(options.disabled ? { enabled: false } : {}),
     name,
@@ -454,6 +510,7 @@ async function buildPortal(
         ? { docs: { content } }
         : {}),
     ...(landing ? { landing } : {}),
+    footer: rel(dir, footerFile),
     ...(o.noConsole ? { console: { enabled: false } } : {}),
     ...(o.requireAuth ? { requireAuth: true } : {}),
     ...(o.search && !external ? { search: o.search } : {}),
@@ -1048,6 +1105,25 @@ export async function setProjectId(
   return true;
 }
 
+/**
+ * Points the folder at another project for good (`apitogo project use`, API-130): `project.id` becomes the given id,
+ * whatever it was. Returns the id it replaced, if any.
+ */
+export async function replaceProjectId(
+  dir: string,
+  projectId: string,
+): Promise<string | undefined> {
+  const { config, resolved } = loadConfigV2(dir);
+  const previous = config.project?.id;
+  if (previous === projectId) return previous;
+  const next = reparse(resolved.configPath, {
+    ...config,
+    project: { ...config.project, id: projectId },
+  });
+  await writeConfig(resolved.configPath, next);
+  return previous;
+}
+
 /** Removes `project.id` when it is the given id: the project is gone, so the link would only point at nothing. */
 export async function clearProjectId(
   dir: string,

package/src/config/v2/starter-landing.ts

@@ -155,3 +155,44 @@ ${plansSection}      <PricingCtaSection
 }
 `;
 }
+
+/**
+ * The portal's footer, shown under every page except the console's. Built from the landing module's footer section so
+ * it matches the home page; the project owns the file, and `portal.footer` in the config points to it (API-129).
+ */
+export function starterFooter(options: {
+  name: string;
+  links: { label: string; href: string }[];
+}): string {
+  const links = options.links
+    .map(
+      (link) =>
+        `          { label: ${JSON.stringify(link.label)}, href: ${JSON.stringify(link.href)} },`,
+    )
+    .join("\n");
+  return `// Your portal's footer, shown under every page except the console's. Edit this file to make it yours, or remove
+// "footer" from portal in apitogo.config.json to have none.
+import { FooterSection } from "@lukoweb/apitogo-module-landing";
+
+const NAME = ${JSON.stringify(options.name)};
+
+export default function Footer() {
+  return (
+    <FooterSection
+      footer={{
+        brand: { name: NAME, tagline: "Documentation, API keys and plans for the ${options.name.replace(/[`$\\"]/g, "")} API." },
+        columns: [
+          {
+            title: "Developers",
+            links: [
+${links}
+            ],
+          },
+        ],
+        copyright: \`© \${new Date().getFullYear()} \${NAME}\`,
+      }}
+    />
+  );
+}
+`;
+}

package/src/config/v2/wrapper.ts

@@ -1,5 +1,6 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { extractGatewayActionKeysFromOpenApiFile } from "../../cli/platform/helpers/openapi-action-keys.js";
 import { docsNavigation } from "./docs-navigation.js";
 import { ConfigError, type ConfigIssue } from "./errors.js";
 import {
@@ -23,7 +24,7 @@ import {
 } from "./manifest.js";
 import { type PortalProfile, portalProfile } from "./portal-profile.js";
 import { protectedRoutesFor } from "./protected-routes.js";
-import type { ResolvedConfigV2 } from "./resolve.js";
+import { isLogoUrl, type ResolvedConfigV2 } from "./resolve.js";
 import { findTsxPages, TSX_PAGE_ELEMENT_PREFIX } from "./tsx-pages.js";
 
 export const WRAPPER_FILE = "apitogo.config.tsx";
@@ -80,6 +81,8 @@ export type PortalPlan = {
     clientId: string;
     scopes: string[];
     audience?: string;
+    /** Try it offers "Signed-in user" only when the gateway checks tokens (API-129). */
+    tokenIdentity?: boolean;
   };
   /** Pricing, subscriptions, API keys and usage pages. */
   plansPlugin?: {
@@ -96,6 +99,10 @@ export type PortalPlan = {
     gatewayBaseUrl?: string;
     /** The plan shown as "Popular": only the one the tenant marked `featured` in plans.json (API-124). */
     featuredPlanSku?: string;
+    /** Try it offers "Signed-in user" only when the gateway checks tokens (API-129). */
+    tokenIdentity?: boolean;
+    /** Lines each plan's card lists, by lowercased sku, from `features` in plans.json (API-129). */
+    planFeatures?: Record<string, string[]>;
   };
   /** Account pages. */
   userPanel: boolean;
@@ -343,6 +350,7 @@ export function buildSiteConfig(
   return {
     site: {
       title: portal?.name ?? resolved.project.name,
+      ...(portal?.logo ? { logo: siteLogo(portal) } : {}),
       ...(plan.preview
         ? { banner: { message: PREVIEW_BANNER_MESSAGE, color: "caution" } }
         : {}),
@@ -448,6 +456,32 @@ 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 header logo as the site takes it: a file of the portal's `public/` folder becomes its address on the site, an https
+ * address stays as it is (API-129). `check` refuses a file outside `public/`.
+ */
+function siteLogo(
+  portal: NonNullable<ResolvedConfigV2["portal"]>,
+): Record<string, unknown> {
+  const logo = portal.logo as NonNullable<typeof portal.logo>;
+  const publicDir = path.join(portal.dir, "public");
+  const src = (file: string) =>
+    isLogoUrl(file)
+      ? file
+      : `/${path.relative(publicDir, file).split(path.sep).join("/")}`;
+  return {
+    src: { light: src(logo.light), dark: src(logo.dark) },
+    alt: logo.alt ?? portal.name,
+  };
+}
+
+/** A content path as the wrapper imports it: through the `content` link next to it, or absolute when outside it. */
+const wrapperImport = (file: string) =>
+  file.startsWith(`${CONTENT_LINK}/`) ? `./${file}` : file;
+
+/** Paths of the console, where the footer is not shown (API-129). */
+export const FOOTER_HIDDEN_PATHS = ["/account", "/login", "/signup"];
+
 /** A React docs page the wrapper imports: `importPath` is relative to the wrapper, through the `content` link. */
 export type WrapperPage = { id: string; importPath: string };
 
@@ -458,6 +492,8 @@ export type WrapperPage = { id: string; importPath: string };
 export function renderWrapper(
   plan: PortalPlan,
   pages: readonly WrapperPage[] = [],
+  /** The portal's footer component (`portal.footer`), relative to the wrapper through the `content` link. */
+  footerImportPath?: string,
 ): string {
   const imports = [
     'import { buildApitogoConfig } from "@lukoweb/apitogo/build-config";',
@@ -466,7 +502,12 @@ export function renderWrapper(
           'import { devPortalBillingPlugin } from "@lukoweb/apitogo-plugin-dev-portal-billing";',
         ]
       : []),
-    ...(pages.length > 0 ? ['import { createElement } from "react";'] : []),
+    ...(pages.length > 0 || footerImportPath
+      ? ['import { createElement } from "react";']
+      : []),
+    ...(footerImportPath
+      ? [`import PortalFooter from ${JSON.stringify(footerImportPath)};`]
+      : []),
     ...pages.map(
       (page, index) =>
         `import TsxPage${index} from ${JSON.stringify(page.importPath)};`,
@@ -513,7 +554,22 @@ export function renderWrapper(
     "",
     // The components go in after buildApitogoConfig: it copies the config with structuredClone, which cannot copy a
     // React element.
-    ...(pages.length > 0
+    ...(footerImportPath
+      ? [
+          "",
+          "// The portal's footer (portal.footer) on every page except the console's.",
+          `const FOOTER_HIDDEN_PATHS = ${JSON.stringify(FOOTER_HIDDEN_PATHS)};`,
+          "const footerSlot = (props: any) =>",
+          "  FOOTER_HIDDEN_PATHS.some(",
+          "    (hidden) =>",
+          "      props.location.pathname === hidden ||",
+          "      props.location.pathname.startsWith(`${hidden}/`),",
+          "  )",
+          "    ? null",
+          "    : createElement(PortalFooter, props);",
+        ]
+      : []),
+    ...(pages.length > 0 || footerImportPath
       ? [
           "const config = buildApitogoConfig({",
           "  ...siteConfig,",
@@ -522,7 +578,12 @@ export function renderWrapper(
           "",
           "export default {",
           "  ...config,",
-          "  navigation: withTsxPages((config as any).navigation ?? []),",
+          ...(pages.length > 0
+            ? ["  navigation: withTsxPages((config as any).navigation ?? []),"]
+            : []),
+          ...(footerImportPath
+            ? ["  slots: { ...(config as any).slots, footer: footerSlot },"]
+            : []),
           "};",
         ]
       : [
@@ -553,6 +614,30 @@ async function readDemoPlans(
   }
 }
 
+/**
+ * The endpoints each preview plan lists, as the deployed portal does (API-129). A plan that names actions
+ * (`includedActions`) lists those; one that names none gets every operation of the gateway's OpenAPI files, which is
+ * what deploy gives it too.
+ */
+export function withPreviewActions(
+  plans: unknown[] | undefined,
+  specs: readonly string[],
+): unknown[] | undefined {
+  if (!plans) return undefined;
+  let all: string[] | undefined;
+  return plans.map((item) => {
+    if (typeof item !== "object" || item === null) return item;
+    const named = (item as { includedActions?: unknown }).includedActions;
+    all ??= [
+      ...new Set(specs.flatMap(extractGatewayActionKeysFromOpenApiFile)),
+    ].sort((a, b) => a.localeCompare(b));
+    return {
+      ...item,
+      includedActionKeys: Array.isArray(named) ? named : all,
+    };
+  });
+}
+
 /** The portal theme file, when it exists and parses. `check` reports an invalid one; the build just skips it. */
 async function readTheme(resolved: ResolvedConfigV2): Promise<unknown> {
   const file = resolved.portal?.theme;
@@ -699,12 +784,37 @@ export async function preparePortal(
     if (featured)
       plan.plansPlugin.featuredPlanSku = featured.sku.trim().toLowerCase();
   }
+  // The cards' own lines, from plans.json: the platform has no such field, so the build brings them (API-129).
+  if (plan.plansPlugin) {
+    const planFeatures: Record<string, string[]> = {};
+    for (const item of (await readDemoPlans(resolved.plans?.file)) ?? []) {
+      const { sku, features } = (item ?? {}) as {
+        sku?: unknown;
+        features?: unknown;
+      };
+      if (typeof sku !== "string" || !Array.isArray(features)) continue;
+      const lines = features.filter(
+        (line): line is string =>
+          typeof line === "string" && line.trim().length > 0,
+      );
+      if (lines.length > 0) planFeatures[sku.trim().toLowerCase()] = lines;
+    }
+    if (Object.keys(planFeatures).length > 0)
+      plan.plansPlugin.planFeatures = planFeatures;
+  }
+  // "Signed-in user" in Try it sends the visitor's token, which only a gateway with `gateway.auth` reads (API-129).
+  const tokenIdentity = resolved.gateway?.auth !== undefined;
+  if (plan.plansPlugin) plan.plansPlugin.tokenIdentity = tokenIdentity;
+  if (plan.auth) plan.auth.tokenIdentity = tokenIdentity;
   // The account pages' "Documentation" link goes to a page the portal really has, or is left out.
   if (plan.plansPlugin && plan.docs) {
+    // With a home page of its own, `/` is the home page and an index page stays at `/index` (API-129).
     const landing = hostedDocRoutes.some(
       (route) => route === "/" || route === "/index",
     )
-      ? "/"
+      ? resolved.portal?.landing && !hostedDocRoutes.includes("/")
+        ? "/index"
+        : "/"
       : pickLandingRoute(hostedDocRoutes, pageOrders);
     if (landing)
       plan.plansPlugin.links = { ...plan.plansPlugin.links, docs: landing };
@@ -740,11 +850,15 @@ export async function preparePortal(
           element: wrapperPages[index]?.id ?? "",
         })),
         pageOrders,
+        { homeTaken: resolved.portal?.landing !== undefined },
       ),
       docsPath: pickLandingRoute(hostedDocRoutes, pageOrders),
       demoPlans:
         plan.demo && plan.plansPlugin
-          ? await readDemoPlans(resolved.plans?.file)
+          ? withPreviewActions(
+              await readDemoPlans(resolved.plans?.file),
+              resolved.gateway?.specs ?? [],
+            )
           : undefined,
       protectedRoutes: protectedRoutesFor({
         requireAuth: resolved.portal?.requireAuth,
@@ -756,7 +870,13 @@ export async function preparePortal(
       }),
     },
   );
-  const wrapper = renderWrapper(plan, wrapperPages);
+  const wrapper = renderWrapper(
+    plan,
+    wrapperPages,
+    resolved.portal?.footer
+      ? wrapperImport(contentFile(resolved.configDir, resolved.portal.footer))
+      : undefined,
+  );
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
   if (options.write !== false) {
     await mkdir(path.dirname(wrapperPath), { recursive: true });