@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/configuration/overview.md

@@ -1,166 +1,97 @@
----
-title: Configuration overview
-sidebar_icon: file-json-2
-description: How APIToGo sites are configured — apitogo.config.json and .env overrides.
----
-
-APIToGo sites are configured primarily with JSON and environment variables:
-
-| File                  | Role                                                                  |
-| --------------------- | --------------------------------------------------------------------- |
-| `apitogo.config.json` | Committed site defaults: site, modules, auth, apis, navigation, theme |
-| `.env`                | Client URLs and publish secrets (`APITOGO_CONFIG_*`, `VITE_*`)        |
-
-For portal fields (plans, auth, backend metadata), see
-**[Site configuration (manifest)](./manifest.md)**.
-
-:::note{title="Security"}
-
-Do not put OIDC client secrets, Stripe keys, or other secrets in JSON. Use `.env` with
-`APITOGO_CONFIG_AUTHENTICATION__*` (never commit those values).
-
-:::
-
-## Minimal example
-
-```json title=config.json
-{
-  "site": {
-    "title": "My API",
-    "logo": {
-      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
-      "alt": "My API",
-      "width": "130px"
-    }
-  },
-  "authentication": {
-    "enabled": true,
-    "type": "dev-portal"
-  },
-  "modules": {
-    "docs": { "files": "/pages/**/*.{md,mdx}" },
-    "landing": { "enabled": true, "path": "/", "layout": "landing" },
-    "userPanel": {
-      "enabled": true,
-      "dashboard": { "enabled": true },
-      "userManagement": { "enabled": true }
-    }
-  },
-  "navigation": [
-    { "type": "category", "label": "Docs", "items": ["introduction"] },
-    { "type": "link", "to": "api", "label": "API Reference" }
-  ],
-  "redirects": [{ "from": "/", "to": "/introduction" }],
-  "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
-}
-```
-
-Scaffolded projects and MCP (`create_dev_portal` / `apply_product_intent`) produce this layout. You
-can change the site via MCP tools or by editing files — see [MCP overview](../mcp/overview.md).
-
-## Modules vs legacy root keys
-
-Prefer `modules.*`:
-
-| Prefer                      | Legacy (still migrated on load)  |
-| --------------------------- | -------------------------------- |
-| `modules.docs`              | root `docs`                      |
-| `modules.userPanel.apiKeys` | root `apiKeys`                   |
-| `modules.userPanel.plans.*` | root `plans` / `pricing.enabled` |
-
-## Common options
-
-These fields usually live in `apitogo.config.json`.
-
-### `apis`
-
-OpenAPI input as a local file or URL. See [API Reference](./api-reference.md).
-
-```json
-{
-  "apis": [
-    {
-      "type": "file",
-      "input": "./apis/openapi.yaml",
-      "path": "api"
-    }
-  ]
-}
-```
-
-### `site`
-
-Site title and logo (`site.title`, `site.logo`).
-
-### `navigation`
-
-Top bar and sidebar: categories, links, custom pages (custom pages with React elements belong in
-TSX). See [Navigation](./navigation.mdx).
-
-### `theme`
-
-Light/dark theme tokens and optional `customCss`. See
-[Colors & theme](../customization/colors-theme.mdx).
-
-### `metadata`
-
-HTML metadata (`title`, `favicon`, `description`, etc.).
-
-### `modules.docs`
-
-Docs glob and options (publish Markdown, LLMs, default page options). Prefer this over root `docs`.
-See [Docs module](./docs.md).
-
-### `sitemap`
-
-```json
-{
-  "sitemap": {
-    "siteUrl": "https://example.com",
-    "changefreq": "daily",
-    "priority": 0.7,
-    "autoLastmod": true,
-    "exclude": ["/404"]
-  }
-}
-```
-
-### `redirects`
-
-```json
-{
-  "redirects": [
-    { "from": "/", "to": "/introduction" },
-    { "from": "/docs", "to": "/introduction" }
-  ]
-}
-```
-
-### `port`, `basePath`, `canonicalUrlOrigin`, `cdnUrl`, `https`
-
-Dev-server and hosting helpers (often in JSON or still settable from a TS config for advanced
-sites):
-
-- `port` — default `3000` (CLI `--port` wins)
-- `basePath` — host under a subpath
-- `canonicalUrlOrigin` — SEO canonical origin
-- `cdnUrl` — string or `{ base, media }`
-- `https` — `{ key, cert, ca? }` for the local HTTPS server
-
-### `enableStatusPages`
-
-When `true` (default), the build emits static status pages such as `404.html` in `dist`.
-
-## Navigation
-
-Put navigation in `apitogo.config.json`, or keep large trees in a separate module (for example
-`sidebar.ts`) and wire them into your site config.
-
-## Related
-
-- [Manifest (`apitogo.config.json`)](./manifest.md)
-- [Make config (CLI)](./make-config.mdx) — interactive wizard (`npx apitogo config`)
-- [Gateway plans](./plans.md)
-- [Authentication](./authentication.md)
-- [MCP overview](../mcp/overview.md)
-- [Shape with CLI](../cli/shape.md)
+---
+title: Configuration overview
+sidebar_icon: file-json-2
+description: >-
+  One file, apitogo.config.json, describes your API product: the portal, the gateway, sign-in and
+  plans. This page shows its sections and where each one is explained.
+---
+
+An APItoGo project is described by **`apitogo.config.json`** at the root of your folder. It has one
+section per service. Leave a section out and that service is not part of the project.
+
+```json title=apitogo.config.json
+{
+  "version": 2,
+  "project": { "name": "Books API" },
+  "portal": {
+    "landing": "apitogo/portal/landing/LandingPage.tsx",
+    "footer": "apitogo/portal/footer/Footer.tsx",
+    "docs": { "content": ["apitogo/portal/pages/**/*.{md,mdx}"] }
+  },
+  "gateway": {
+    "origin": { "mode": "managed", "source": "server", "runtime": "nodejs" },
+    "specs": ["apitogo/apis/openapi.yaml"]
+  },
+  "identity": {},
+  "plans": {}
+}
+```
+
+`apitogo create` and `apitogo add` write this file for you, and `apitogo config` changes it. You can
+also edit it by hand: `apitogo check` tells you what is wrong before anything is deployed.
+
+## Sections
+
+| Section    | What it is                                                                 | Reference                      |
+| ---------- | -------------------------------------------------------------------------- | ------------------------------ |
+| `version`  | Always `2`                                                                 |                                |
+| `project`  | The project's name, and its id once `apitogo project create` has linked it | [Below](#project)              |
+| `portal`   | The developer portal: docs pages, home page, footer, logo, theme, console  | [Portal](./portal.md)          |
+| `gateway`  | Your API behind the gateway: where it runs, its OpenAPI files, the rules   | [Gateway](./gateway.md)        |
+| `identity` | Sign-in for the people who use your portal                                 | [Sign-in](./authentication.md) |
+| `plans`    | The plans people pick, and Stripe for the paid ones                        | [Plans](./plans.md)            |
+
+The API page of the portal is made from the gateway's OpenAPI files. See
+[API reference](./api-reference.md).
+
+## The folder
+
+Everything the services use, besides the config, lives in the `apitogo/` folder:
+
+```
+apitogo.config.json
+apitogo/
+├─ plans.json               the plans (when the project has plans)
+├─ apis/openapi.yaml        your OpenAPI file (or wherever gateway.specs points)
+└─ portal/
+   ├─ pages/                docs pages: Markdown (.md, .mdx) and React (.tsx)
+   ├─ landing/LandingPage.tsx   the home page
+   ├─ footer/Footer.tsx     the footer
+   ├─ theme.json            colors and fonts
+   └─ public/               images and files served as they are (logo.svg, ...)
+```
+
+`apitogo/.state/` holds what the CLI generates and what it deployed. It ignores itself in git, and
+you never edit it.
+
+## project
+
+```json
+"project": { "id": "fe3a12b0-fbaf-4315-b37f-b731d930ee57", "name": "Books API" }
+```
+
+- `name`: the project's name, used as the portal's name unless `portal.name` says otherwise.
+- `id`: the platform project this folder deploys to. `apitogo project create` writes it, and
+  `apitogo project use <id>` moves the folder to another project. See
+  [CLI commands](../cli/commands.md).
+
+## Secrets
+
+The config never holds a secret. Where a service needs one (a Stripe key, an OIDC client secret), it
+names a project secret:
+
+```json
+"plans": { "billing": { "apiKey": "secret:STRIPE_API_KEY" } }
+```
+
+Store the value with `npx apitogo secrets set STRIPE_API_KEY`. Deploy asks for the secrets it needs
+and stores them for you. A value written straight into the config is refused.
+
+## Check before you deploy
+
+```bash
+npx apitogo check
+```
+
+`check` reads the config and the files it names, and says what is missing or wrong, with a hint for
+each problem. `deploy` runs the same checks first.

package/docs/configuration/plans.md

@@ -1,154 +1,144 @@
 ---
-title: Gateway plans
+title: Plans
 sidebar_icon: tags
-description:
-  Configure end-user API plans in apitogo.config.json — pricing, rate limits, quotas, and publish
-  behavior.
+description: >-
+  The plans your API's users pick: limits, prices, features and endpoints in apitogo/plans.json, and
+  Stripe for the paid ones.
 ---
 
-**Gateway plans** (also called API plans) are what your **end users** subscribe to.
+**Plans** are what the people who use your API choose: a free tier, a paid tier, a contact-us tier.
+Each one has its own limits, and the gateway enforces them on every call made with that plan's API
+key.
 
-- **`/pricing`** — public catalog. Visitors choose a plan before signup. Signed-in users still see
-  this page; it must not redirect to `/account/plans`.
-- **`/account/plans`** — authenticated billing. Sign-in required. Manage and change subscriptions.
+The portal shows them on **`/pricing`** (public) and **`/account/plans`**, where signed-in people
+subscribe, switch and cancel.
 
-They are separate from **platform hosting** (Free / Starter / Professional on APItoGo), which you
-select with `npx apitogo deploy --platform-plan`.
+## Turn plans on
 
-Store the catalog under `modules.userPanel.plans.items` in `apitogo.config.json`.
-
-## Shape with the CLI
+```json title=apitogo.config.json
+{
+  "plans": {}
+}
+```
 
-In a config version 2 project, plans live in `apitogo/plans.json`. `npx apitogo config` adds them
-interactively (title, price, rate limit, monthly quota) or with `--plan`. A plan with the same `sku`
-is replaced.
+The plans themselves live in **`apitogo/plans.json`**. `apitogo add plans` creates it, and
+`apitogo config` adds plans interactively or with `--plan` (a plan with the same `sku` is replaced):
 
 ```bash
-npx apitogo config
-# choose plan → enter title, price, policies → done when finished
 npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
 ```
 
-## Canonical shape
+## plans.json
 
-```json
+```json title=apitogo/plans.json
 {
-  "modules": {
-    "userPanel": {
-      "plans": {
-        "enabled": true,
-        "items": [
-          {
-            "sku": "free",
-            "displayName": "Free",
-            "priceAmount": 0,
-            "limits": {
-              "rateLimit": { "calls": 100, "renewalPeriodSeconds": 60 },
-              "quota": { "calls": 50000, "renewalPeriodDays": 30 }
-            }
-          },
-          {
-            "sku": "pro",
-            "displayName": "Pro",
-            "priceAmount": 29,
-            "priceCurrency": "usd",
-            "billingPeriod": "month",
-            "limits": {
-              "rateLimit": { "calls": 1000, "renewalPeriodSeconds": 60 },
-              "quota": { "calls": 500000, "renewalPeriodDays": 30 }
-            }
-          }
-        ]
+  "version": 1,
+  "plans": [
+    {
+      "sku": "free",
+      "displayName": "Free",
+      "default": true,
+      "limits": {
+        "rateLimit": { "calls": 60, "periodSeconds": 60 },
+        "quota": { "calls": 1000, "periodDays": 30 }
       }
+    },
+    {
+      "sku": "pro",
+      "displayName": "Pro",
+      "priceAmount": 19,
+      "priceCurrency": "usd",
+      "billingInterval": "month",
+      "featured": true,
+      "limits": { "rateLimit": { "calls": 600, "periodSeconds": 60 } },
+      "features": ["Email support", "Usage history"]
+    },
+    {
+      "sku": "enterprise",
+      "displayName": "Enterprise",
+      "pricingModel": "custom",
+      "priceLabel": "Let's talk"
     }
-  }
+  ]
 }
 ```
 
-- **`sku`** — stable identifier (used in checkout URLs and gateway sync).
-- **`displayName`** — label on `/pricing`.
-- **`priceAmount`** — `0` for free tiers; greater than zero for paid plans (USD by default).
-- **`pricingModel`** — `fixed` (default) or `custom`. See
-  [Custom pricing](#custom-pricing-contact-sales).
-- **`priceLabel`** — optional text shown instead of the price, such as `"Let's talk"` (max 64
-  characters).
-- **`limits`** — rate limit and quota policies (see below). Encoded `limitsJson` strings are still
-  accepted on load.
+| Field             | What it does                                                                     |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `sku`             | The plan's id, unique in the file                                                |
+| `displayName`     | The name on the pricing page                                                     |
+| `default`         | The plan the portal offers first                                                 |
+| `limits`          | `rateLimit` (`calls` per `periodSeconds`) and `quota` (`calls` per `periodDays`) |
+| `priceAmount`     | The price; `0` or left out is free                                               |
+| `priceCurrency`   | A currency code such as `usd` or `eur`                                           |
+| `billingInterval` | `month` or `year`                                                                |
+| `pricingModel`    | `fixed` (default) or `custom` for a contact-us plan                              |
+| `priceLabel`      | The text shown instead of a price, for a contact-us plan                         |
+| `featured`        | Shown as **Popular**                                                             |
+| `features`        | Extra lines on the plan's card                                                   |
+| `includedActions` | The endpoints the plan includes, such as `get:/orders`; left out, all of them    |
+| `sortOrder`       | The plan's place on the page; by default the file order                          |
 
-Enable the catalog with `modules.userPanel.plans.enabled: true`. Legacy root `plans` is migrated on
-load.
+An unknown field is refused, so a typo never goes unnoticed.
 
-## limits schema
+## What a pricing card shows
 
-```json
-{
-  "rateLimit": { "calls": 100, "renewalPeriodSeconds": 60 },
-  "quota": { "calls": 50000, "renewalPeriodDays": 30 }
-}
-```
+Each card lists, in this order:
+
+1. The limits: `600 requests per minute`, `1,000 requests / month`
+2. The plan's `features`
+3. The endpoints it includes: the ones in `includedActions`, or every operation of the gateway
+
+`npx apitogo run` shows the same cards as the deployed portal.
 
-- **rateLimit** — maximum calls per renewal window (per minute when `renewalPeriodSeconds` is 60).
-- **quota** — longer-window cap (per 30 days when `renewalPeriodDays` is 30).
+## Paid plans
 
-New plans include **all** discovered OpenAPI operations unless you set `includedActionKeys`. After
-OpenAPI is deployed, you can scope a plan to specific operations with `includedActionKeys` (for
-example `get:/orders/{id}`). Edit those fields in `apitogo.config.json` — see
-[Manifest](./manifest.md).
+A plan with a price is paid through **your own Stripe account**. When the file has one, deploy asks
+for your Stripe secret key, then for the webhook signing secret, and stores both as project secrets.
+[Set up Stripe for paid plans](../guides/stripe-setup.mdx) shows where to find them.
 
-## Custom pricing (contact sales)
+Free and contact-us plans need no Stripe at all.
 
-Set `pricingModel: "custom"` for plans with negotiated prices, such as an Enterprise tier. Leave
-`priceAmount` at `0` or omit it.
+The `billing` settings are only needed to change the defaults:
 
 ```json
-{
-  "sku": "enterprise",
-  "displayName": "Enterprise",
-  "pricingModel": "custom",
-  "priceLabel": "Let's talk"
+"plans": {
+  "billing": {
+    "apiKey": "secret:STRIPE_API_KEY",
+    "webhookSecret": "secret:STRIPE_WEBHOOK",
+    "successUrl": "https://portal.example.com/account/plans",
+    "cancelUrl": "https://portal.example.com/pricing"
+  }
 }
 ```
 
-On `/pricing`, custom plans show `priceLabel` (or **Custom**) and a **Contact sales** button. The
-button opens a public `/contact-sales` form instead of Stripe checkout or registration. Visitors
-don't need an account.
+Selling paid plans needs the **Starter** or **Professional** hosting plan. On **Free**, deploy stops
+at a paid plan and says so.
 
-Each submission is emailed to the project's **sales contact email**, or to the project owner's email
-when none is set. Custom plans can't be subscribed to through checkout. Custom plans are available
-on every platform plan, including Free.
+## Contact-us plans
 
-## Publish
+`"pricingModel": "custom"` makes a plan you price per customer. Its card shows `priceLabel` (or
+**Custom**) and a **Contact sales** button, which opens a public form instead of a checkout. Each
+request is emailed to the project's sales contact, or to its owner.
 
-Gateway plans are applied when you run:
+## Deploy
 
 ```bash
-npx apitogo deploy
+npx apitogo deploy --only plans
 ```
 
-`npx apitogo deploy` syncs plans from the manifest to the platform gateway. Paid plans require
-Stripe secrets in `.env` before publish — see [Go live with CLI](../cli/go-live.md).
-
-## Platform hosting vs gateway plans
-
-| Kind                    | What it is                                     | How                                  |
-| ----------------------- | ---------------------------------------------- | ------------------------------------ |
-| **Platform hosting**    | APItoGo bill for hosting your portal + API hub | `npx apitogo deploy --platform-plan` |
-| **Gateway / API plans** | What your customers pay for API access         | `modules.userPanel.plans.items`      |
-
-### Free platform limitations
-
-The **Free** platform plan cannot:
+deploys the plans, their limits on the gateway and the pricing page. A plain `npx apitogo deploy`
+does it together with everything else.
 
-- Publish **paid** gateway plans (`priceAmount > 0`)
-- Attach a **custom domain** to the dev portal
+## Hosting plans are something else
 
-Use **Starter** or **Professional** for paid API tiers, Stripe checkout, and custom domains. If your
-manifest has paid plans and you try `npx apitogo deploy --platform-plan free`, deploy is blocked
-until you upgrade or zero/remove those paid plans.
+| Kind                 | What it is                                        | Where                           |
+| -------------------- | ------------------------------------------------- | ------------------------------- |
+| Your plans           | What your users pay you for using your API        | `apitogo/plans.json`            |
+| APItoGo hosting plan | What you pay APItoGo: Free, Starter, Professional | `apitogo project create --plan` |
 
 ## Related
 
-- [Manifest](./manifest.md)
-- [Make config (CLI)](./make-config.mdx)
-- [Authentication](./authentication.md)
-- [Go live with CLI](../cli/go-live.md)
+- [Set up Stripe for paid plans](../guides/stripe-setup.mdx)
+- [Your customers' account pages](../guides/customer-account.md)
+- [Gateway](./gateway.md)

package/docs/configuration/portal.md

@@ -0,0 +1,116 @@
+---
+title: Portal
+sidebar_icon: layout-template
+description: >-
+  The portal section of apitogo.config.json: docs pages, home page, footer, logo, theme, console,
+  search and who may see the portal.
+---
+
+The `portal` section is your developer portal: the docs, the API page, the home page and the console
+where people sign in, pick a plan and get API keys.
+
+```json title=apitogo.config.json
+{
+  "portal": {
+    "name": "Books API",
+    "docs": { "content": ["apitogo/portal/pages/**/*.{md,mdx}"] },
+    "landing": "apitogo/portal/landing/LandingPage.tsx",
+    "footer": "apitogo/portal/footer/Footer.tsx",
+    "logo": "apitogo/portal/public/logo.svg",
+    "theme": "apitogo/portal/theme.json",
+    "search": "pagefind",
+    "requireAuth": false
+  }
+}
+```
+
+`"portal": {}` is enough: every setting has a default. `apitogo add portal` writes the section and
+its starter files.
+
+## Settings
+
+| Setting       | Default                              | What it does                                                                |
+| ------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `name`        | `project.name`                       | The name in the header and the page titles                                  |
+| `docs`        | `apitogo/portal/pages/**/*.{md,mdx}` | Where the docs pages are, or an external docs site ([below](#docs))         |
+| `landing`     | none                                 | A React file shown at `/`, the home page                                    |
+| `footer`      | none                                 | A React file shown under every page except the console's                    |
+| `logo`        | none (the header shows `name`)       | The header logo ([below](#logo))                                            |
+| `theme`       | `apitogo/portal/theme.json`          | Colors and fonts ([Colors & theme](../customization/colors-theme.mdx))      |
+| `console`     | `{ "enabled": true }`                | The sign-in, plans, keys and usage pages, when identity or plans is on      |
+| `search`      | `pagefind`                           | `pagefind`, `inkeep` or `none`                                              |
+| `requireAuth` | `false`                              | Only signed-in people may see the portal ([below](#who-may-see-the-portal)) |
+| `dir`         | `apitogo/portal`                     | The portal's folder, if you keep it somewhere else                          |
+| `enabled`     | `true`                               | `false` keeps the section but leaves the portal out of deploys              |
+
+## docs
+
+The docs pages are the Markdown and React files in `apitogo/portal/pages/`. Name other places with
+`content` (globs, relative to the config):
+
+```json
+"docs": { "content": ["docs/**/*.{md,mdx}", "guides/**/*.md"] }
+```
+
+React pages (`.tsx`) in the same folders are found too. The sidebar is built from the files: a
+folder becomes a section, and `order` in a page's frontmatter sorts it. See
+[Writing](../writing.mdx) and [Custom pages](../guides/custom-pages.md) for React pages.
+
+If your docs live on another site, link it instead. The portal then has no docs pages of its own:
+
+```json
+"docs": { "provider": "external", "url": "https://docs.example.com" }
+```
+
+## Home page and footer
+
+`landing` and `footer` each name a React file in your folder. `apitogo add portal` writes both,
+built from the sections of `@lukoweb/apitogo-module-landing`, and you change them freely. Remove the
+setting to have none. See [Landing page](../customization/landing-page.md) and
+[Footer](./footer.mdx).
+
+When there is a home page, `/` shows it, and an `index` page of the docs opens at `/index`.
+
+## logo
+
+An image in the portal's `public/` folder, or an `https://` address:
+
+```json
+"logo": "apitogo/portal/public/logo.svg"
+```
+
+One image per color scheme, with the text read out by screen readers:
+
+```json
+"logo": {
+  "light": "apitogo/portal/public/logo.svg",
+  "dark": "apitogo/portal/public/logo-dark.svg",
+  "alt": "Books API"
+}
+```
+
+`apitogo check` refuses a file that does not exist or is not in `public/`.
+
+## Who may see the portal
+
+By default everyone may read the docs and the API page. `requireAuth` asks people to sign in first
+(it needs `identity`):
+
+```json
+"requireAuth": true
+```
+
+Keep some pages public:
+
+```json
+"requireAuth": { "exclude": ["/introduction", "/pricing"] }
+```
+
+## Console
+
+The console pages appear on their own when the project has `identity` (sign-in) or `plans` (pricing,
+API keys, usage). Turn them off with:
+
+```json
+"console": { "enabled": false }
+```