@lukoweb/apitogo 0.2.23 → 0.2.25

package/docs/configuration/overview.md

@@ -1,166 +1,166 @@
----
-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: 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)

package/docs/configuration/plans.md

@@ -1,153 +1,153 @@
----
-title: Gateway plans
-sidebar_icon: tags
-description:
-  Configure end-user API plans in apitogo.config.json — pricing, rate limits, quotas, and publish
-  behavior.
----
-
-**Gateway plans** (also called API plans) are what your **end users** subscribe to.
-
-- **`/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.
-
-They are separate from **platform hosting** (Free / Starter / Professional on APItoGo), which you
-select with `npx apitogo deploy --platform-plan`.
-
-Store the catalog under `modules.userPanel.plans.items` in `apitogo.config.json`.
-
-## Shape with the CLI
-
-`npx apitogo config` can add plans interactively (title, price, rate limit, monthly quota). Each
-plan is written immediately. You can also edit the manifest by hand or use MCP
-`update_dev_portal_manifest`.
-
-```bash
-npx apitogo config
-# choose plan → enter title, price, policies → done when finished
-```
-
-## Canonical shape
-
-```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 }
-            }
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-- **`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.
-
-Enable the catalog with `modules.userPanel.plans.enabled: true`. Legacy root `plans` is migrated on
-load.
-
-## limits schema
-
-```json
-{
-  "rateLimit": { "calls": 100, "renewalPeriodSeconds": 60 },
-  "quota": { "calls": 50000, "renewalPeriodDays": 30 }
-}
-```
-
-- **rateLimit** — maximum calls per renewal window (per minute when `renewalPeriodSeconds` is 60).
-- **quota** — longer-window cap (per 30 days when `renewalPeriodDays` is 30).
-
-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).
-
-## Custom pricing (contact sales)
-
-Set `pricingModel: "custom"` for plans with negotiated prices, such as an Enterprise tier. Leave
-`priceAmount` at `0` or omit it.
-
-```json
-{
-  "sku": "enterprise",
-  "displayName": "Enterprise",
-  "pricingModel": "custom",
-  "priceLabel": "Let's talk"
-}
-```
-
-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.
-
-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.
-
-## Publish
-
-Gateway plans are applied when you run:
-
-```bash
-npx apitogo deploy
-```
-
-`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:
-
-- Publish **paid** gateway plans (`priceAmount > 0`)
-- Attach a **custom domain** to the dev portal
-
-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.
-
-## Related
-
-- [Manifest](./manifest.md)
-- [Make config (CLI)](./make-config.mdx)
-- [Authentication](./authentication.md)
-- [Go live with CLI](../cli/go-live.md)
+---
+title: Gateway plans
+sidebar_icon: tags
+description:
+  Configure end-user API plans in apitogo.config.json — pricing, rate limits, quotas, and publish
+  behavior.
+---
+
+**Gateway plans** (also called API plans) are what your **end users** subscribe to.
+
+- **`/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.
+
+They are separate from **platform hosting** (Free / Starter / Professional on APItoGo), which you
+select with `npx apitogo deploy --platform-plan`.
+
+Store the catalog under `modules.userPanel.plans.items` in `apitogo.config.json`.
+
+## Shape with the CLI
+
+`npx apitogo config` can add plans interactively (title, price, rate limit, monthly quota). Each
+plan is written immediately. You can also edit the manifest by hand or use MCP
+`update_dev_portal_manifest`.
+
+```bash
+npx apitogo config
+# choose plan → enter title, price, policies → done when finished
+```
+
+## Canonical shape
+
+```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 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+- **`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.
+
+Enable the catalog with `modules.userPanel.plans.enabled: true`. Legacy root `plans` is migrated on
+load.
+
+## limits schema
+
+```json
+{
+  "rateLimit": { "calls": 100, "renewalPeriodSeconds": 60 },
+  "quota": { "calls": 50000, "renewalPeriodDays": 30 }
+}
+```
+
+- **rateLimit** — maximum calls per renewal window (per minute when `renewalPeriodSeconds` is 60).
+- **quota** — longer-window cap (per 30 days when `renewalPeriodDays` is 30).
+
+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).
+
+## Custom pricing (contact sales)
+
+Set `pricingModel: "custom"` for plans with negotiated prices, such as an Enterprise tier. Leave
+`priceAmount` at `0` or omit it.
+
+```json
+{
+  "sku": "enterprise",
+  "displayName": "Enterprise",
+  "pricingModel": "custom",
+  "priceLabel": "Let's talk"
+}
+```
+
+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.
+
+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.
+
+## Publish
+
+Gateway plans are applied when you run:
+
+```bash
+npx apitogo deploy
+```
+
+`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:
+
+- Publish **paid** gateway plans (`priceAmount > 0`)
+- Attach a **custom domain** to the dev portal
+
+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.
+
+## Related
+
+- [Manifest](./manifest.md)
+- [Make config (CLI)](./make-config.mdx)
+- [Authentication](./authentication.md)
+- [Go live with CLI](../cli/go-live.md)