@lukoweb/apitogo 0.2.46 → 0.2.49

package/docs/configuration/plans.md

@@ -1,153 +1,154 @@
----
-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
+
+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.
+
+```bash
+npx apitogo config
+# choose plan → enter title, price, policies → done when finished
+npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
+```
+
+## 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)

package/docs/guides/custom-pages.md

@@ -1,110 +1,111 @@
----
-title: Custom pages
-sidebar_icon: layers-3
----
-
-If you want to include pages in your documentation that have greater flexibility than MDX pages, it
-is possible to include custom pages of your own.
-
-These pages are typically built using standard React markup and can borrow from a set of prebuilt
-components that APIToGo already has such as buttons, links and headers.
-
-Start by creating the page you want to add.
-
-## CLI scaffold
-
-`npx apitogo config` can create a starter page under `pages/` and wire it into navigation
-immediately. Choose `page` in the wizard loop, then edit the generated `.tsx` file.
-
-Predefined UI components (Callout, Card, Button, Heading, and more) are documented under
-[/docs/components](/docs/components).
-
-## Setup a custom page
-
-Each custom page is a page component of its own and lives in a `src` directory at the root of your
-project. Let's create the `<MyCustomPage />` component as an example.
-
-From the root of your project run this command:
-
-```bash
-touch src/MyCustomPage.tsx
-```
-
-You can now open `/src/MyCustomPage.tsx` in the editor of your choice. It will be empty.
-
-Copy and paste this code to implement the page:
-
-```tsx
-import { Button, Head, Link } from "@lukoweb/apitogo/components";
-
-export const MyCustomPage = () => {
-  return (
-    <section className="">
-      <Head>
-        <title>My Custom Page</title>
-      </Head>
-      <div>
-        <p>Welcome to MyCustomPage</p>
-      </div>
-    </section>
-  );
-};
-```
-
-## Configuration
-
-In the [APIToGo Configuration](../configuration/overview.md) you will need to do the following:
-
-### Config that embeds JSX
-
-If you embed React components in config (for example custom pages), use a JSX-capable config module
-and import your page component from there.
-
-### Import Your Module
-
-Import the `<MyCustomPage />` component that you created.
-
-```typescript
-import { MyCustomPage } from "./src/MyCustomPage";
-```
-
-### Add a navigation entry
-
-Add a `custom-page` item to the `navigation` configuration. Each page you want to add to the site
-must be its own object.
-
-The `path` key can be set to whatever you like. This will appear as part of the URL in the address
-bar of the browser.
-
-The `element` key references the name of the custom page component that you want to load.
-
-```typescript
-{
-  // ...
-  navigation: [
-    {
-      type: "custom-page",
-      path: "/a-custom-page",
-      element: <MyCustomPage />,
-    },
-  ]
-  // ...
-}
-```
-
-This configuration will allow APIToGo to load the contents of the `<MyCustomPage />` component when
-a user clicks on a link that points to `/a-custom-page`.
-
-## Troubleshooting
-
-### Updating Your `tsconfig.json`
-
-Your `include` property in `tsconfig.json` should automatically be updated to reflect the new custom
-pages, but in case it isn't, it should look like this:
-
-```json
-{
-  ...
-  "include": ["src", "src/MyCustomPage.tsx"]
-}
-```
+---
+title: Custom pages
+sidebar_icon: layers-3
+---
+
+If you want to include pages in your documentation that have greater flexibility than MDX pages, it
+is possible to include custom pages of your own.
+
+These pages are typically built using standard React markup and can borrow from a set of prebuilt
+components that APIToGo already has such as buttons, links and headers.
+
+Start by creating the page you want to add.
+
+## CLI scaffold
+
+`npx apitogo config` can create a starter Markdown page at `apitogo/portal/pages/<slug>.mdx`. Choose
+`page` in the wizard loop, or pass `--page-slug` and `--page-title`. The sidebar is built from the
+pages folder, so no navigation entry is needed.
+
+Predefined UI components (Callout, Card, Button, Heading, and more) are documented under
+[/docs/components](/docs/components).
+
+## Setup a custom page
+
+Each custom page is a page component of its own and lives in a `src` directory at the root of your
+project. Let's create the `<MyCustomPage />` component as an example.
+
+From the root of your project run this command:
+
+```bash
+touch src/MyCustomPage.tsx
+```
+
+You can now open `/src/MyCustomPage.tsx` in the editor of your choice. It will be empty.
+
+Copy and paste this code to implement the page:
+
+```tsx
+import { Button, Head, Link } from "@lukoweb/apitogo/components";
+
+export const MyCustomPage = () => {
+  return (
+    <section className="">
+      <Head>
+        <title>My Custom Page</title>
+      </Head>
+      <div>
+        <p>Welcome to MyCustomPage</p>
+      </div>
+    </section>
+  );
+};
+```
+
+## Configuration
+
+In the [APIToGo Configuration](../configuration/overview.md) you will need to do the following:
+
+### Config that embeds JSX
+
+If you embed React components in config (for example custom pages), use a JSX-capable config module
+and import your page component from there.
+
+### Import Your Module
+
+Import the `<MyCustomPage />` component that you created.
+
+```typescript
+import { MyCustomPage } from "./src/MyCustomPage";
+```
+
+### Add a navigation entry
+
+Add a `custom-page` item to the `navigation` configuration. Each page you want to add to the site
+must be its own object.
+
+The `path` key can be set to whatever you like. This will appear as part of the URL in the address
+bar of the browser.
+
+The `element` key references the name of the custom page component that you want to load.
+
+```typescript
+{
+  // ...
+  navigation: [
+    {
+      type: "custom-page",
+      path: "/a-custom-page",
+      element: <MyCustomPage />,
+    },
+  ]
+  // ...
+}
+```
+
+This configuration will allow APIToGo to load the contents of the `<MyCustomPage />` component when
+a user clicks on a link that points to `/a-custom-page`.
+
+## Troubleshooting
+
+### Updating Your `tsconfig.json`
+
+Your `include` property in `tsconfig.json` should automatically be updated to reflect the new custom
+pages, but in case it isn't, it should look like this:
+
+```json
+{
+  ...
+  "include": ["src", "src/MyCustomPage.tsx"]
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.46",
+  "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 } }
+  }
+}