@lukoweb/apitogo 0.2.46 → 0.2.49

package/src/config/v2/__fixtures__/scenario-h-full-stack.json

@@ -1,28 +1,28 @@
-{
-  "$schema": "https://apitogo.com/schema/config-v2.json",
-  "version": 2,
-  "layout": "embedded",
-  "project": { "id": "prj_123", "name": "acme-orders" },
-  "gateway": {
-    "origin": {
-      "mode": "managed",
-      "source": "server",
-      "runtime": "nodejs",
-      "runtimeVersion": "NODE_22_LTS"
-    },
-    "specs": ["server/docs/swagger.yaml"],
-    "auth": { "mode": "identity" }
-  },
-  "identity": { "native": true },
-  "plans": {
-    "billing": {
-      "provider": "stripe",
-      "apiKey": "secret:STRIPE_API_KEY",
-      "webhookSecret": "secret:STRIPE_WEBHOOK_SECRET"
-    }
-  },
-  "portal": {
-    "name": "Acme Orders",
-    "docs": { "content": ["docs/**/*.{md,mdx}"] }
-  }
-}
+{
+  "$schema": "https://apitogo.com/schema/config-v2.json",
+  "version": 2,
+  "layout": "embedded",
+  "project": { "id": "prj_123", "name": "acme-orders" },
+  "gateway": {
+    "origin": {
+      "mode": "managed",
+      "source": "server",
+      "runtime": "nodejs",
+      "runtimeVersion": "NODE_22_LTS"
+    },
+    "specs": ["server/docs/swagger.yaml"],
+    "auth": { "mode": "identity" }
+  },
+  "identity": { "native": true },
+  "plans": {
+    "billing": {
+      "provider": "stripe",
+      "apiKey": "secret:STRIPE_API_KEY",
+      "webhookSecret": "secret:STRIPE_WEBHOOK_SECRET"
+    }
+  },
+  "portal": {
+    "name": "Acme Orders",
+    "docs": { "content": ["docs/**/*.{md,mdx}"] }
+  }
+}

package/src/config/v2/billing.ts

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import type { ResolvedConfigV2 } from "./resolve.js";
+
+/**
+ * Billing (decision 21, narrowed): Stripe is the only payment provider. Billing is on exactly when the plan catalog has a
+ * plan with a price, so a project with free and contact-us plans needs no Stripe key and is never asked for one.
+ */
+
+/** The project secret that holds the Stripe key when `plans.billing.apiKey` names none. */
+export const DEFAULT_STRIPE_KEY_SECRET = "STRIPE_API_KEY";
+
+type PriceFields = { pricingModel?: unknown; priceAmount?: unknown };
+
+/** A plan someone pays for: a fixed price above 0. A contact-us (custom) plan is not paid here. */
+export function isPaidPlan(plan: PriceFields): boolean {
+  return (
+    plan.pricingModel !== "custom" &&
+    typeof plan.priceAmount === "number" &&
+    plan.priceAmount > 0
+  );
+}
+
+/** The skus of the paid plans in the plans file. A missing or unreadable file has none; the plans rules report it. */
+export async function paidPlanSkus(
+  resolved: ResolvedConfigV2,
+): Promise<string[]> {
+  const file = resolved.plans?.file;
+  if (!file) return [];
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8")) as {
+      plans?: unknown;
+    };
+    if (!Array.isArray(raw.plans)) return [];
+    return raw.plans
+      .filter(
+        (plan): plan is PriceFields & { sku?: unknown } =>
+          typeof plan === "object" && plan !== null && isPaidPlan(plan),
+      )
+      .map((plan) => String(plan.sku ?? "?"));
+  } catch {
+    return [];
+  }
+}
+
+/** True when the plans service takes payments: Stripe is not switched off and a plan has a price. */
+export async function billingNeeded(
+  resolved: ResolvedConfigV2,
+): Promise<boolean> {
+  const plans = resolved.plans;
+  if (!plans?.enabled || plans.billing.provider !== "stripe") return false;
+  return (await paidPlanSkus(resolved)).length > 0;
+}
+
+/** The name of the secret that holds the Stripe key (`secret:NAME` in `plans.billing.apiKey`, default `STRIPE_API_KEY`). */
+export function stripeKeySecretName(resolved: ResolvedConfigV2): string {
+  const ref = resolved.plans?.billing.apiKey;
+  const match = ref ? /^secret:(.+)$/.exec(ref) : null;
+  return match?.[1] ?? DEFAULT_STRIPE_KEY_SECRET;
+}

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

@@ -1,72 +1,72 @@
-import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
-
-/** Label of the one header tab that holds the sidebar made from the docs pages. */
-export const DOCS_NAVIGATION_LABEL = "Documentation";
-
-type Branch = { pages: Set<string>; folders: Map<string, Branch> };
-
-const emptyBranch = (): Branch => ({ pages: new Set(), folders: new Map() });
-
-/** "getting-started" becomes "Getting started". */
-export function folderLabel(name: string): string {
-  const words = name.replace(/[-_]+/g, " ").trim();
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-
-const byName = (a: string, b: string) => a.localeCompare(b);
-
-const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
-  const pages = [...branch.pages].sort((a, b) =>
-    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
-  );
-  const folders = [...branch.folders.keys()].sort(byName);
-  return [
-    // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
-    ...pages.map(
-      (page): InputNavigationItem =>
-        page === "index"
-          ? {
-              type: "doc",
-              file: `${prefix}${page}`,
-              path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`,
-            }
-          : `${prefix}${page}`,
-    ),
-    ...folders.map(
-      (folder): InputNavigationItem => ({
-        type: "category",
-        label: folderLabel(folder),
-        collapsible: true,
-        collapsed: false,
-        items: toItems(
-          branch.folders.get(folder) ?? emptyBranch(),
-          `${prefix}${folder}/`,
-        ),
-      }),
-    ),
-  ];
-};
-
-/**
- * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
- * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`).
- * Without pages there is nothing to navigate, so the result is empty.
- */
-export function docsNavigation(routes: string[]): InputNavigationItem[] {
-  const root = emptyBranch();
-  for (const route of routes) {
-    const parts = route.split("/").filter(Boolean);
-    const page = parts.pop();
-    if (!page) continue;
-    const branch = parts.reduce((current, folder) => {
-      const next = current.folders.get(folder) ?? emptyBranch();
-      current.folders.set(folder, next);
-      return next;
-    }, root);
-    branch.pages.add(page);
-  }
-  const items = toItems(root, "");
-  return items.length === 0
-    ? []
-    : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];
-}
+import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
+
+/** Label of the one header tab that holds the sidebar made from the docs pages. */
+export const DOCS_NAVIGATION_LABEL = "Documentation";
+
+type Branch = { pages: Set<string>; folders: Map<string, Branch> };
+
+const emptyBranch = (): Branch => ({ pages: new Set(), folders: new Map() });
+
+/** "getting-started" becomes "Getting started". */
+export function folderLabel(name: string): string {
+  const words = name.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+const byName = (a: string, b: string) => a.localeCompare(b);
+
+const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
+  const pages = [...branch.pages].sort((a, b) =>
+    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
+  );
+  const folders = [...branch.folders.keys()].sort(byName);
+  return [
+    // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
+    ...pages.map(
+      (page): InputNavigationItem =>
+        page === "index"
+          ? {
+              type: "doc",
+              file: `${prefix}${page}`,
+              path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`,
+            }
+          : `${prefix}${page}`,
+    ),
+    ...folders.map(
+      (folder): InputNavigationItem => ({
+        type: "category",
+        label: folderLabel(folder),
+        collapsible: true,
+        collapsed: false,
+        items: toItems(
+          branch.folders.get(folder) ?? emptyBranch(),
+          `${prefix}${folder}/`,
+        ),
+      }),
+    ),
+  ];
+};
+
+/**
+ * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
+ * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`).
+ * Without pages there is nothing to navigate, so the result is empty.
+ */
+export function docsNavigation(routes: string[]): InputNavigationItem[] {
+  const root = emptyBranch();
+  for (const route of routes) {
+    const parts = route.split("/").filter(Boolean);
+    const page = parts.pop();
+    if (!page) continue;
+    const branch = parts.reduce((current, folder) => {
+      const next = current.folders.get(folder) ?? emptyBranch();
+      current.folders.set(folder, next);
+      return next;
+    }, root);
+    branch.pages.add(page);
+  }
+  const items = toItems(root, "");
+  return items.length === 0
+    ? []
+    : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];
+}

package/src/config/v2/errors.ts

@@ -1,42 +1,42 @@
-import { ApitogoError } from "../../lib/util/invariant.js";
-
-/**
- * One problem in a config file. `code` is stable and safe to match on, `path` is the dotted config path
- * (for example `gateway.origin.mode`), `hint` says how to fix it.
- */
-export type ConfigIssue = {
-  code: string;
-  path: string;
-  message: string;
-  hint?: string;
-};
-
-export function formatConfigIssue(issue: ConfigIssue): string {
-  const hint = issue.hint ? ` ${issue.hint}` : "";
-  const rest = issue.message.slice(issue.path.length);
-  // Several documented messages already begin with their own path; do not print it twice.
-  const startsWithPath =
-    issue.path !== "" &&
-    issue.message.startsWith(issue.path) &&
-    (rest === "" || /^[\s:]/.test(rest));
-  const text = startsWithPath
-    ? issue.message
-    : `${issue.path === "" ? "(root)" : issue.path}: ${issue.message}`;
-  return `${text}${hint} [${issue.code}]`;
-}
-
-/** Thrown when an `apitogo.config.json` cannot be loaded. Carries every problem found, not just the first. */
-export class ConfigError extends ApitogoError {
-  public readonly issues: readonly ConfigIssue[];
-
-  constructor(file: string, issues: readonly ConfigIssue[]) {
-    super(
-      `${file} has ${issues.length} problem${issues.length === 1 ? "" : "s"}:\n${issues
-        .map((issue) => `  - ${formatConfigIssue(issue)}`)
-        .join("\n")}`,
-      { title: "Invalid apitogo config" },
-    );
-    this.name = "ConfigError";
-    this.issues = issues;
-  }
-}
+import { ApitogoError } from "../../lib/util/invariant.js";
+
+/**
+ * One problem in a config file. `code` is stable and safe to match on, `path` is the dotted config path
+ * (for example `gateway.origin.mode`), `hint` says how to fix it.
+ */
+export type ConfigIssue = {
+  code: string;
+  path: string;
+  message: string;
+  hint?: string;
+};
+
+export function formatConfigIssue(issue: ConfigIssue): string {
+  const hint = issue.hint ? ` ${issue.hint}` : "";
+  const rest = issue.message.slice(issue.path.length);
+  // Several documented messages already begin with their own path; do not print it twice.
+  const startsWithPath =
+    issue.path !== "" &&
+    issue.message.startsWith(issue.path) &&
+    (rest === "" || /^[\s:]/.test(rest));
+  const text = startsWithPath
+    ? issue.message
+    : `${issue.path === "" ? "(root)" : issue.path}: ${issue.message}`;
+  return `${text}${hint} [${issue.code}]`;
+}
+
+/** Thrown when an `apitogo.config.json` cannot be loaded. Carries every problem found, not just the first. */
+export class ConfigError extends ApitogoError {
+  public readonly issues: readonly ConfigIssue[];
+
+  constructor(file: string, issues: readonly ConfigIssue[]) {
+    super(
+      `${file} has ${issues.length} problem${issues.length === 1 ? "" : "s"}:\n${issues
+        .map((issue) => `  - ${formatConfigIssue(issue)}`)
+        .join("\n")}`,
+      { title: "Invalid apitogo config" },
+    );
+    this.name = "ConfigError";
+    this.issues = issues;
+  }
+}