@lukoweb/apitogo 0.2.47 → 0.2.49

package/docs/cli/shape.md

@@ -50,9 +50,10 @@ continues until you type `done`:
 
 Fonts and colors are **not** prompted. See [Colors & theme](../customization/colors-theme.mdx).
 
-**Paid plans:** a plan with a price needs `plans.billing.provider: "stripe"`, and **Starter** or
-**Professional** platform hosting on deploy. **Free** cannot publish paid gateway plans or custom
-domains.
+**Paid plans:** payments go through Stripe. Once a plan has a price, `npx apitogo deploy` asks for
+your Stripe secret key (if the project has none yet) and stores it as a project secret. Free and
+contact-us plans need no key. Paid plans also need **Starter** or **Professional** platform hosting;
+**Free** cannot publish paid gateway plans or custom domains.
 
 Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
 [Gateway plans](../configuration/plans.md)

package/docs/cli/walkthrough.md

@@ -37,7 +37,7 @@ below use the installed CLI through `npx apitogo`.
 ```bash
 npx apitogo add identity
 npx apitogo add gateway --origin proxy --url https://httpbin.org --auth identity --create-spec
-npx apitogo add plans --template free --billing none
+npx apitogo add plans --template free
 ```
 
 | Service  | What it gives you                                                                               |
@@ -117,32 +117,21 @@ Professional plan with APItoGo, and your own Stripe account. Your customers pay
    opens the platform's checkout for the hosting fee. A project that already exists on the Free plan
    cannot be moved: create a new one. See
    [Selling paid plans needs Starter or Professional](./commands.md#selling-paid-plans-needs-starter-or-professional).
-2. In your Stripe account, copy the secret key (it starts with `sk_test_` while you test). Store it
-   as a project secret. The command asks for the value, so it stays out of the config:
-
-   ```bash
-   npx apitogo secrets set STRIPE_KEY
-   ```
-
-3. Turn billing on in `apitogo.config.json`:
-
-   ```json
-   "plans": {
-     "billing": { "provider": "stripe", "apiKey": "secret:STRIPE_KEY" }
-   }
-   ```
-
-4. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
-   `"billingPeriod": "month"`. Its limits cannot be higher than your platform plan allows. A plan
-   with a price is refused while billing is off, so nobody is offered a plan they cannot pay for.
-5. Deploy: `npx apitogo deploy`. The output says whether Stripe is in test or live mode and prints
-   your portal's webhook address.
-6. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
+2. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
+   `"billingInterval": "month"`. Its limits cannot be higher than your platform plan allows.
+   Payments go through Stripe; nothing else in the config changes.
+3. Deploy: `npx apitogo deploy`. Because a plan now has a price, deploy asks for your Stripe secret
+   key (it starts with `sk_test_` while you test) and stores it as the project secret
+   `STRIPE_API_KEY`, so it stays out of your files. You can also store it beforehand with
+   `npx apitogo secrets set STRIPE_API_KEY`. The output says whether Stripe is in test or live mode
+   and prints your portal's webhook address.
+4. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
    `customer.subscription.updated`, `customer.subscription.deleted` and `invoice.payment_failed`.
    Copy the signing secret (it starts with `whsec_`), store it with
-   `npx apitogo secrets set STRIPE_WEBHOOK`, add `"webhookSecret": "secret:STRIPE_WEBHOOK"` next to
-   `apiKey`, and deploy again. Until then a payment does not activate the plan, because the portal
-   cannot confirm it came from Stripe.
+   `npx apitogo secrets set STRIPE_WEBHOOK`, add
+   `"plans": { "billing": { "webhookSecret": "secret:STRIPE_WEBHOOK" } }` to `apitogo.config.json`,
+   and deploy again. Until then a payment does not activate the plan, because the portal cannot
+   confirm it came from Stripe.
 
 While you use a test key, pay with [Stripe's test cards](https://docs.stripe.com/testing). No real
 money moves. Never type a live key until you have tested the whole path.

package/docs/configuration/make-config.mdx

@@ -44,8 +44,9 @@ On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at
 - **`plan`**: title, fixed or custom price, rate limit per minute, quota per 30 days; added to
   `plans.json`
 
-If you add a **paid** plan while `plans.billing.provider` is not `stripe`, the CLI warns that deploy
-will refuse it. Paid plans also need Starter or Professional platform hosting.
+Payments go through Stripe. When you add a **paid** plan, `npx apitogo deploy` asks for your Stripe
+secret key the first time (if the project has none yet). Free and contact-us plans need no key. Paid
+plans also need Starter or Professional platform hosting.
 
 ## Options
 

package/package.json

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

package/src/config/v2/__fixtures__/scenario-a-docs-only.json

@@ -1,6 +1,6 @@
-{
-  "version": 2,
-  "layout": "standalone",
-  "project": { "name": "my-docs" },
-  "portal": { "name": "My Docs" }
-}
+{
+  "version": 2,
+  "layout": "standalone",
+  "project": { "name": "my-docs" },
+  "portal": { "name": "My Docs" }
+}

package/src/config/v2/__fixtures__/scenario-b-managed-origin.json

@@ -1,14 +1,14 @@
-{
-  "version": 2,
-  "layout": "embedded",
-  "gateway": {
-    "origin": {
-      "mode": "managed",
-      "source": ".",
-      "runtime": "nodejs",
-      "runtimeVersion": "NODE_22_LTS",
-      "exclude": ["apitogo/**", "node_modules/**"]
-    },
-    "specs": ["openapi.yaml"]
-  }
-}
+{
+  "version": 2,
+  "layout": "embedded",
+  "gateway": {
+    "origin": {
+      "mode": "managed",
+      "source": ".",
+      "runtime": "nodejs",
+      "runtimeVersion": "NODE_22_LTS",
+      "exclude": ["apitogo/**", "node_modules/**"]
+    },
+    "specs": ["openapi.yaml"]
+  }
+}

package/src/config/v2/__fixtures__/scenario-c-proxy-oidc.json

@@ -1,15 +1,15 @@
-{
-  "version": 2,
-  "layout": "standalone",
-  "gateway": {
-    "origin": { "mode": "proxy", "url": "https://api.acme.com" },
-    "specs": ["apis/openapi.yaml"],
-    "auth": {
-      "mode": "oidc",
-      "metadataUrl": "https://idp.acme.com/.well-known/openid-configuration",
-      "issuers": ["https://idp.acme.com/"],
-      "audiences": ["api://acme-orders"]
-    },
-    "policies": { "rateLimit": { "calls": 60, "periodSeconds": 60 } }
-  }
-}
+{
+  "version": 2,
+  "layout": "standalone",
+  "gateway": {
+    "origin": { "mode": "proxy", "url": "https://api.acme.com" },
+    "specs": ["apis/openapi.yaml"],
+    "auth": {
+      "mode": "oidc",
+      "metadataUrl": "https://idp.acme.com/.well-known/openid-configuration",
+      "issuers": ["https://idp.acme.com/"],
+      "audiences": ["api://acme-orders"]
+    },
+    "policies": { "rateLimit": { "calls": 60, "periodSeconds": 60 } }
+  }
+}

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;
+  }
+}