@lukoweb/apitogo 0.2.47 → 0.2.50

package/src/config/v2/rules.ts

@@ -2,9 +2,11 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 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 type { ConfigV2 } from "./schema.js";
+import { findTsxPages } from "./tsx-pages.js";
 
 /**
  * The rules of `apitogo check` that need no network (Reference, section 2). Online rules (provider capabilities,
@@ -276,6 +278,8 @@ async function docsContentRule(
       ? await glob(include, { nodir: true, ignore, absolute: true })
       : [];
   if (matches.length > 0) return;
+  // React pages (.tsx) next to the docs count too.
+  if ((await findTsxPages(patterns)).length > 0) return;
 
   const shown = config.portal?.docs?.content ?? [
     path.relative(resolved.configDir, patterns[0] ?? ""),
@@ -284,7 +288,7 @@ async function docsContentRule(
     code: "PORTAL_DOCS_EMPTY",
     path: "portal.docs",
     message: `portal.docs matched 0 files (${shown.join(", ")}). The site will only contain the API reference.`,
-    hint: "Add .md or .mdx files, or point docs.content at your existing docs.",
+    hint: "Add .md, .mdx or .tsx pages, or point docs.content at your existing docs.",
   });
 }
 
@@ -657,9 +661,9 @@ function identityRules(
 // --- plans (2.6) ----------------------------------------------------------------------------------------------------
 
 async function plansRules(
-  config: ConfigV2,
   resolved: ResolvedConfigV2,
   out: Collector,
+  paid: boolean,
 ) {
   const plans = resolved.plans;
   if (!plans?.enabled) return;
@@ -683,16 +687,8 @@ async function plansRules(
     }
   }
 
-  if (plans.billing.provider === "stripe") {
-    if (!config.plans?.billing?.apiKey) {
-      out.error({
-        code: "PLANS_BILLING_INCOMPLETE",
-        path: "plans.billing.apiKey",
-        message:
-          "plans.billing.apiKey is required when billing.provider is stripe.",
-        hint: 'Set it to a secret reference, for example "secret:STRIPE_API_KEY".',
-      });
-    }
+  // Billing is on only when a plan has a price. The Stripe key defaults to the STRIPE_API_KEY secret.
+  if (paid) {
     const headless = !(resolved.portal?.enabled === true);
     for (const field of ["successUrl", "cancelUrl"] as const) {
       if (headless && !plans.billing[field]) {
@@ -711,11 +707,22 @@ async function plansRules(
 
 function secretRules(
   config: ConfigV2,
+  resolved: ResolvedConfigV2,
   context: CheckContext,
   out: Collector,
   skipped: string[],
+  paid: boolean,
 ) {
-  const refs = collectSecretRefs(config);
+  // The billing secrets matter only when a plan has a price. The Stripe key is then needed even when the config does not
+  // name it (it defaults to STRIPE_API_KEY). `apitogo deploy` asks for it, so a missing key is a warning, not an error.
+  const stripeKeyPath = "plans.billing.apiKey";
+  const named = collectSecretRefs(config).filter(
+    (ref) => paid || !ref.path.startsWith("plans.billing"),
+  );
+  const refs =
+    paid && !named.some((ref) => ref.path === stripeKeyPath)
+      ? [...named, { name: stripeKeySecretName(resolved), path: stripeKeyPath }]
+      : named;
   if (refs.length === 0) return;
   if (!context.knownSecrets) {
     skipped.push(
@@ -724,7 +731,14 @@ function secretRules(
     return;
   }
   for (const ref of refs) {
-    if (!context.knownSecrets.has(ref.name)) {
+    if (ref.path === stripeKeyPath && !context.knownSecrets.has(ref.name)) {
+      out.warn({
+        code: "SECRET_NOT_SET",
+        path: ref.path,
+        message: `a plan has a price, and the Stripe key (secret ${ref.name}) is not set yet.`,
+        hint: `apitogo deploy asks for it. Or run: apitogo secrets set ${ref.name}`,
+      });
+    } else if (!context.knownSecrets.has(ref.name)) {
       out.error({
         code: "SECRET_NOT_SET",
         path: ref.path,
@@ -751,12 +765,13 @@ export async function checkConfigV2(
     warn: (issue) => warnings.push(issue),
   };
 
+  const paid = await billingNeeded(resolved);
   dependencyRules(config, resolved, out);
-  secretRules(config, context, out, skipped);
+  secretRules(config, resolved, context, out, skipped, paid);
   await portalRules(config, resolved, out);
   await gatewayRules(resolved, out);
   identityRules(config, resolved, out);
-  await plansRules(config, resolved, out);
+  await plansRules(resolved, out, paid);
 
   return { errors, warnings, skipped };
 }

package/src/config/v2/services.ts

@@ -9,6 +9,7 @@ import {
 } from "node:fs/promises";
 import path from "node:path";
 import { ApitogoError } from "../../lib/util/invariant.js";
+import { isPaidPlan } from "./billing.js";
 import {
   FULL_SERVER_HEALTH_PATH,
   FULL_SERVER_TIMEOUT_SECONDS,
@@ -182,7 +183,6 @@ export type AddOptions = {
   plans?: {
     file?: string;
     template?: "free" | "tiered" | "none";
-    billing?: "stripe" | "none";
   };
 };
 
@@ -773,15 +773,8 @@ async function buildPlans(
       : isFilled(options.template)
         ? "starter"
         : "free");
-  // Only paid plans need a billing provider. A catalog of free plans takes no payment, so its default is `none` and the
-  // config checks clean right away; the tiered template (paid plans) defaults to Stripe, whose key is set with `secrets set`.
-  const billing = o.billing ?? (template === "tiered" ? "stripe" : "none");
-  if (template === "tiered" && billing === "none") {
-    throw new ServiceEditError(
-      "The tiered template has paid plans, which need a billing provider.",
-      "Use --billing stripe, or --template free.",
-    );
-  }
+  // Stripe is the only billing provider, and it is needed only once a plan has a price: the config names no billing
+  // settings, and `apitogo deploy` asks for the Stripe key (secret STRIPE_API_KEY) the first time a paid plan is deployed.
   const file = o.file ? insideProject(dir, o.file, "Plans file") : undefined;
   const target = file
     ? path.join(dir, file)
@@ -791,22 +784,14 @@ async function buildPlans(
     target,
     `${JSON.stringify({ version: 1, plans: PLAN_TEMPLATES[template] }, null, 2)}\n`,
   );
-  if (billing === "stripe") {
+  if (PLAN_TEMPLATES[template].some((plan) => isPaidPlan(plan))) {
     context.notes.push(
-      "Set the billing key: apitogo secrets set STRIPE_API_KEY",
+      "A plan has a price, so payments go through Stripe: apitogo deploy asks for your Stripe secret key.",
     );
   }
   return {
     ...(options.disabled ? { enabled: false } : {}),
     ...(file ? { file } : {}),
-    ...(billing === "stripe"
-      ? {
-          billing: {
-            provider: "stripe" as const,
-            apiKey: "secret:STRIPE_API_KEY",
-          },
-        }
-      : { billing: { provider: "none" as const } }),
   };
 }
 

package/src/config/v2/tsx-pages.ts

@@ -0,0 +1,100 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import globParent from "glob-parent";
+import { folderLabel } from "./docs-navigation.js";
+import { toGlobPath } from "./resolve.js";
+
+/**
+ * React pages next to the Markdown docs: a `.tsx` file in a docs folder is a page whose default export is the page
+ * component. Its address follows the same rule as a Markdown page (the path inside the folder, without the extension),
+ * so `pages/guides/quickstart.tsx` is `/guides/quickstart`. A file or folder whose name starts with `_` is a helper
+ * (shared components, hooks), not a page.
+ */
+export type TsxPage = {
+  /** `/guides/quickstart`. */
+  route: string;
+  /** Absolute path of the component file. */
+  file: string;
+  /** Sidebar label: `export const title = "..."` in the file, or the file name. */
+  label: string;
+};
+
+const IGNORED = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+
+/**
+ * A helper next to the pages, not a page: anything under a name that starts with `_`, tests and stories. Checked on
+ * the path inside the docs folder (the glob library's `ignore` does not match absolute Windows paths).
+ */
+export function isTsxHelper(relative: string): boolean {
+  return (
+    relative.split("/").some((part) => part.startsWith("_")) ||
+    /\.(test|spec|stories)\.tsx$/.test(relative) ||
+    relative.split("/").includes("node_modules")
+  );
+}
+
+/** The `.tsx` patterns for the docs content globs: every file below each glob's folder. Negated globs stay as they are. */
+export function tsxPagePatterns(contentGlobs: readonly string[]): string[] {
+  const globs = contentGlobs.map(toGlobPath);
+  const included = globs.filter((pattern) => !pattern.startsWith("!"));
+  const excluded = globs.filter((pattern) => pattern.startsWith("!"));
+  return [
+    ...new Set(
+      included.map((pattern) =>
+        path.posix.join(globParent(pattern), "**", "*.tsx"),
+      ),
+    ),
+    ...excluded,
+  ];
+}
+
+const TITLE =
+  /export\s+const\s+title\s*(?::\s*string\s*)?=\s*(["'`])((?:\\.|(?!\1).)*)\1/;
+
+/** The label a page shows in the sidebar. */
+export function tsxPageLabel(source: string, file: string): string {
+  const match = TITLE.exec(source);
+  if (match?.[2]) return match[2].replace(/\\(.)/g, "$1");
+  const name = path.basename(file, ".tsx");
+  return folderLabel(
+    name === "index" ? path.basename(path.dirname(file)) : name,
+  );
+}
+
+/** The React pages the docs content globs reach, sorted by address. */
+export async function findTsxPages(
+  contentGlobs: readonly string[],
+): Promise<TsxPage[]> {
+  const patterns = tsxPagePatterns(contentGlobs);
+  const ignore = [
+    ...IGNORED,
+    ...patterns
+      .filter((pattern) => pattern.startsWith("!"))
+      .map((pattern) => pattern.slice(1)),
+  ];
+  const found = new Map<string, TsxPage>();
+  for (const pattern of patterns.filter((p) => !p.startsWith("!"))) {
+    const parent = globParent(pattern);
+    const files = await glob(pattern, {
+      absolute: true,
+      posix: true,
+      nodir: true,
+      ignore,
+    });
+    for (const raw of files.sort()) {
+      // On Windows the glob library answers with the extended form `//?/C:/...`, which would not relate to `parent`.
+      const file = raw.replace(/^\/\/\?\//, "");
+      const relative = path.posix.relative(parent, file);
+      if (isTsxHelper(relative)) continue;
+      const route = `/${relative.replace(/\.tsx$/, "")}`;
+      if (found.has(route)) continue;
+      const source = await readFile(file, "utf8").catch(() => "");
+      found.set(route, { route, file, label: tsxPageLabel(source, file) });
+    }
+  }
+  return [...found.values()].sort((a, b) => a.route.localeCompare(b.route));
+}
+
+/** The placeholder a sidebar item carries until the generated wrapper puts the component in its place. */
+export const TSX_PAGE_ELEMENT_PREFIX = "apitogo:tsx-page:";

package/src/config/v2/workspace.ts

@@ -5,6 +5,7 @@ import { glob } from "glob";
 import { ensureStateDir } from "./layout.js";
 import { linkDirectory } from "./link-directory.js";
 import type { ResolvedConfigV2 } from "./resolve.js";
+import { tsxPagePatterns } from "./tsx-pages.js";
 import { CONTENT_LINK, type PreparedPortal } from "./wrapper.js";
 
 const exists = (file: string) =>
@@ -92,6 +93,10 @@ export async function portalArtifactHash(
   const portal = resolved.portal;
   const patterns = [
     ...(portal?.docs.content ?? []),
+    // React docs pages and the helpers next to them are imported by the wrapper, so their contents decide the build too.
+    ...(portal?.docs.provider === "apitogo"
+      ? tsxPagePatterns(portal.docs.content)
+      : []),
     ...(resolved.gateway?.specs ?? []),
     ...(portal
       ? [portal.theme, path.join(portal.dir, "public", "**", "*")]

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";
 
@@ -424,8 +425,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 +443,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 +486,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 +636,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 +689,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 +712,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 });