@lukoweb/apitogo 0.2.46 → 0.2.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,124 +1,97 @@
1
- ---
2
- title: Make config (CLI)
3
- navigation_label: Make config
4
- sidebar_icon: file-cog
5
- description:
6
- Create or update apitogo.config.json from your pages folder, OpenAPI, gateway plans, and optional
7
- site settings.
8
- ---
9
-
10
- The **`npx apitogo config`** command writes **`apitogo.config.json`**. It can scaffold a portal
11
- project (package.json, tsconfig, landing and user-panel stubs, thin `apitogo.config.tsx`) when those
12
- files are missing, merge **site / theme / authentication** from flags, run an **interactive wizard**
13
- on a TTY (apply each change immediately), scan `pages/` for navigation, and wire OpenAPI plus an
14
- **API Reference** link.
15
-
16
- Landing and user panel are **always enabled** on new configs. **Authentication is enabled by
17
- default** on new scaffolds. The command does **not** change `redirects`.
18
-
19
- ## Prerequisites
20
-
21
- Install the CLI first — see [Install the CLI](../cli/setup.md). In short:
22
-
23
- - **New site:** `npx @lukoweb/apitogo@latest init` (scaffolds into `./dev-portal` by default)
24
-
25
- Run config from the project root with `npx apitogo config`.
26
-
27
- ## What it does
28
-
29
- 1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and
30
- **`tsconfig.json`** when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing
31
- packages.
32
- 2. **Creates `apitogo.config.json`** when missing, using the current portal template (`site`,
33
- `theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**).
34
- Creates a thin **`apitogo.config.tsx`** wrapper only if that file does not already exist
35
- (existing TSX is left alone).
36
- 3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or the
37
- interactive wizard.
38
- 4. **Merges `navigation`** from `.md` / `.mdx` / `.tsx` files under your pages directory into a
39
- Documentation category when those files exist. **Missing or empty `pages/` is fine** (common for
40
- portal-only sites) — existing navigation is left alone. Other nav items are kept. Use
41
- **`--force`** to rebuild Documentation items from disk when pages are present (API Reference is
42
- still kept when OpenAPI is wired).
43
- 5. **Wires OpenAPI** when a spec is found (non-interactive) or when you enter a path in the wizard:
44
- `apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api`
45
- if that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
46
- example `./openapi.yaml` or `../api/openapi.yaml`).
47
- 6. **Interactive only** — can set **backend** (`sourceDirectory`, `runtime`, `runtimeVersion`),
48
- scaffold **custom pages** under `pages/`, and append **gateway plans** to
49
- `modules.userPanel.plans.items`. Each choice is written immediately.
50
-
51
- ## Interactive wizard
52
-
53
- On a TTY, bare `npx apitogo config` opens the wizard (no `-i` required). `-i` still works as an
54
- alias. Use `--no-interactive` (or pass flags like `--title`) for CI / non-TTY.
55
-
56
- ```bash
57
- npx apitogo config
58
- ```
59
-
60
- 1. **Loop** until you type `done` (default):
61
- - **`backend`** — source directory, runtime (`dotnet` / `nodejs` / `python`), platform
62
- `runtimeVersion` (writes `backend` in `apitogo.config.json` immediately)
63
- - **`openapi`** — path to your OpenAPI file (relative link in config; empty skips)
64
- - **`page`** — page title + URL path (writes `pages/<slug>.tsx` and wires navigation immediately)
65
- - **`plan`** — plan title, price (USD/month), rate limit (calls/min), monthly quota (writes
66
- immediately)
67
- 2. **Wrap-up** — links to [docs.apitogo.com](https://docs.apitogo.com) for further configuration
68
-
69
- The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL.
70
- Authentication stays **enabled**; `npx apitogo deploy` writes
71
- `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` to `.env` after the portal backend is provisioned.
72
-
73
- If you add a **paid** plan (`priceAmount > 0`), the CLI warns that **Free platform hosting cannot
74
- publish paid gateway plans or custom domains** — use Starter or Professional on deploy.
75
-
76
- See [Gateway plans](./plans.md) and [Shape with CLI](../cli/shape.md).
77
-
78
- ## Usage
79
-
80
- Run from your project root (where `apitogo.config.json` and `package.json` live):
81
-
82
- ```bash
83
- npx apitogo config
84
- ```
85
-
86
- ### Options
87
-
88
- | Option | Description |
89
- | ------------------------- | ----------------------------------------------------------------------- |
90
- | `--pages-dir <dir>` | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`) |
91
- | `--dir <path>` | Project root (default: current directory) |
92
- | `--interactive` / `-i` | Force the wizard (default on TTY). Use `--no-interactive` to skip. |
93
- | `--title <string>` | Set `site.title` (non-interactive) |
94
- | `--site <json>` | Deep-merge a JSON object into `site` |
95
- | `--theme <json>` | Deep-merge a JSON object into `theme` |
96
- | `--authentication <json>` | Deep-merge a JSON object into `authentication` (secrets stay in `.env`) |
97
- | `--force` | Replace Documentation nav items from disk |
98
-
99
- Examples:
100
-
101
- ```bash
102
- npx apitogo config
103
- npx apitogo config --title "Books API"
104
- npx apitogo config --theme '{"light":{"primary":"#111111"}}'
105
- npx apitogo config --no-interactive
106
- ```
107
-
108
- Theme and fonts are edited in `apitogo.config.json` or via MCP — not in the interactive wizard. See
109
- [Colors & theme](../customization/colors-theme.mdx) and [Fonts](../customization/fonts.md).
110
-
111
- There is **no `--modules` flag** for landing or user-panel toggles. Interactive mode **does** update
112
- `modules.userPanel.plans` when you add plans.
113
-
114
- ## When not to use it
115
-
116
- - You need a fully custom navigation order — skip `--force` or maintain navigation by hand.
117
- - You want to change landing module home content — edit `landing/LandingPage.tsx`.
118
-
119
- ## See also
120
-
121
- - [Manifest (`apitogo.config.json`)](./manifest.md)
122
- - [Gateway plans](./plans.md)
123
- - [Navigation](./navigation.md)
124
- - [Shape with CLI](../cli/shape.md)
1
+ ---
2
+ title: Make config (CLI)
3
+ navigation_label: Make config
4
+ sidebar_icon: file-cog
5
+ description:
6
+ Change a config version 2 project from the CLI: portal name, API code, OpenAPI files, docs pages
7
+ and plans.
8
+ ---
9
+
10
+ The **`npx apitogo config`** command changes a project made by `apitogo create` or `apitogo init`
11
+ (config version 2). It edits **`apitogo.config.json`**, writes docs pages under
12
+ **`apitogo/portal/pages/`**, and keeps plans in **`apitogo/plans.json`**.
13
+
14
+ Every change to `apitogo.config.json` is checked against the version 2 schema before it is written.
15
+ An invalid change is refused and the file stays as it was.
16
+
17
+ The command does not create a project. In a folder without `apitogo.config.json`, or with an old
18
+ version 1 config, it stops and points to `apitogo create`.
19
+
20
+ ## What goes where
21
+
22
+ | You change | Where it is written |
23
+ | ------------------- | ---------------------------------------------------------------- |
24
+ | Portal display name | `portal.name` in `apitogo.config.json` |
25
+ | API code (backend) | `gateway.origin` (`mode: managed`, `source`, `runtime`, version) |
26
+ | OpenAPI file | `gateway.specs` in `apitogo.config.json` |
27
+ | Docs page | `apitogo/portal/pages/<slug>.mdx` (the config does not change) |
28
+ | Plan | `apitogo/plans.json` (or the file in `plans.file`) |
29
+
30
+ The portal builds its sidebar from the pages folder, so adding a page needs no navigation entry. A
31
+ page in `guides/quickstart.mdx` shows under a **Guides** section at `/guides/quickstart`.
32
+
33
+ Changing a gateway or plan needs that service in the project. Add it first with
34
+ `apitogo add gateway` or `apitogo add plans`.
35
+
36
+ ## Interactive wizard
37
+
38
+ On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at once. Type `done`
39
+ (the default) to finish.
40
+
41
+ - **`backend`**: folder of your API code, runtime (`nodejs` / `python` / `dotnet`) and version
42
+ - **`openapi`**: an OpenAPI file to add to `gateway.specs`
43
+ - **`page`**: page title and URL path; writes `apitogo/portal/pages/<slug>.mdx`
44
+ - **`plan`**: title, fixed or custom price, rate limit per minute, quota per 30 days; added to
45
+ `plans.json`
46
+
47
+ Payments go through Stripe. When you add a **paid** plan, `npx apitogo deploy` asks for your Stripe
48
+ secret key the first time (if the project has none yet). Free and contact-us plans need no key. Paid
49
+ plans also need Starter or Professional platform hosting.
50
+
51
+ ## Options
52
+
53
+ | Option | Description |
54
+ | --------------------------- | --------------------------------------------------------------------- |
55
+ | `--interactive` / `-i` | Force the wizard (default on TTY). Use `--no-interactive` to skip it. |
56
+ | `--title <name>` | Set `portal.name` |
57
+ | `--source <dir>` | Folder of your API code (`gateway.origin.source`, mode `managed`) |
58
+ | `--runtime <name>` | Runtime of `--source`: `nodejs` (default), `python` or `dotnet` |
59
+ | `--runtime-version <v>` | Runtime version, for example `NODE_22_LTS` |
60
+ | `--openapi <file>` | Add an OpenAPI file to `gateway.specs` |
61
+ | `--page-slug <path>` | Add a page at `apitogo/portal/pages/<path>.mdx` |
62
+ | `--page-title <title>` | Title of the page (required when adding) |
63
+ | `--page-content <markdown>` | Markdown body of the page |
64
+ | `--page-update` | Change an existing page instead of adding one |
65
+ | `--plan <json>` | Add a plan to `plans.json`, or replace the plan with the same `sku` |
66
+ | `--patch <json>` | Deep-merge a JSON object into `apitogo.config.json` |
67
+ | `--json` | Print a JSON summary on stdout |
68
+
69
+ A plan uses the `plans.json` shape:
70
+
71
+ ```json
72
+ {
73
+ "sku": "starter",
74
+ "displayName": "Starter",
75
+ "limits": {
76
+ "rateLimit": { "calls": 100, "periodSeconds": 60 },
77
+ "quota": { "calls": 50000, "periodDays": 30 }
78
+ }
79
+ }
80
+ ```
81
+
82
+ Examples:
83
+
84
+ ```bash
85
+ npx apitogo config
86
+ npx apitogo config --title "Books API"
87
+ npx apitogo config --page-slug guides/quickstart --page-title "Quickstart"
88
+ npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
89
+ npx apitogo config --source server --runtime nodejs --runtime-version NODE_22_LTS
90
+ npx apitogo config --patch '{"portal":{"search":"none"}}'
91
+ ```
92
+
93
+ ## See also
94
+
95
+ - [Manifest (`apitogo.config.json`)](./manifest.md)
96
+ - [Gateway plans](./plans.md)
97
+ - [Shape with CLI](../cli/shape.md)
@@ -1,128 +1,129 @@
1
- # Site configuration (apitogo.config.json)
2
-
3
- Dev portal sites use `apitogo.config.json` for site settings, plans, authentication, and backend
4
- metadata, with optional `.env` overrides for secrets and local tweaks.
5
-
6
- ## Files
7
-
8
- | File | Purpose |
9
- | --------------------- | ----------------------------------------------------------- |
10
- | `apitogo.config.json` | Committed defaults: site, modules, authentication, backend |
11
- | `.env` | Public client vars + publish secrets via `APITOGO_CONFIG_*` |
12
-
13
- ## Canonical shape
14
-
15
- ```json
16
- {
17
- "site": {
18
- "title": "My API",
19
- "logo": {
20
- "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
21
- "alt": "My API",
22
- "width": "130px"
23
- }
24
- },
25
- "authentication": {
26
- "enabled": true,
27
- "type": "dev-portal",
28
- "apiBaseUrl": "https://your-dev-portal-api.example.com"
29
- },
30
- "gateway": {
31
- "authMode": "bringYourOwnOidc",
32
- "oidcMetadataUrl": "https://login.example.com/.well-known/openid-configuration",
33
- "publicRoutes": ["/health"],
34
- "cors": {
35
- "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
36
- }
37
- },
38
- "modules": {
39
- "docs": { "files": "/pages/**/*.{md,mdx}" },
40
- "landing": { "enabled": true, "path": "/", "layout": "landing" },
41
- "userPanel": {
42
- "enabled": true,
43
- "dashboard": { "enabled": true },
44
- "userManagement": { "enabled": true },
45
- "plans": {
46
- "enabled": true,
47
- "items": [
48
- {
49
- "sku": "free",
50
- "displayName": "Free",
51
- "priceAmount": 0
52
- }
53
- ]
54
- }
55
- }
56
- },
57
- "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
58
- }
59
- ```
60
-
61
- - **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
62
- - **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
63
- - **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
64
- `modules.userPanel.plans.items`. Add plans with `npx apitogo config` or edit the manifest by hand.
65
- See [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
66
- - **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
67
- - **Gateway:** top-level `gateway` (not under `authentication`). See [Gateway CORS](#gateway-cors)
68
- and [Gateway plans](./plans.md).
69
-
70
- ## Gateway CORS
71
-
72
- Browser calls from your developer portal (and any other SPA) to the API gateway are cross-origin.
73
- APItoGo always allows the portal site origin. Add extra origins under `gateway.cors.allowedOrigins`
74
- when tenant apps or local frontends call the gateway:
75
-
76
- ```json
77
- {
78
- "gateway": {
79
- "cors": {
80
- "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
81
- }
82
- }
83
- }
84
- ```
85
-
86
- | Rule | Detail |
87
- | --------------- | ----------------------------------------------------------------------------------- |
88
- | Portal origin | Always allowed by the platform (`https://{your-portal-host}`). Do not list it here. |
89
- | Extra origins | Absolute `http://` or `https://` origins only — no path, query, or fragment. |
90
- | Wildcard | `"*"` is allowed (replaces the list; credentials stay off). |
91
- | Empty / omitted | Portal playground still works; only extras are missing. |
92
-
93
- Apply with `npx apitogo deploy` / `publish_dev_portal` so APIM policies pick up the change.
94
-
95
- ## Environment variables
96
-
97
- Public client URL (mirrors `authentication.apiBaseUrl`):
98
-
99
- ```sh
100
- VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
101
- ```
102
-
103
- Nested config overrides (uppercase SCREAMING_SNAKE path segments; camelCase still accepted):
104
-
105
- ```sh
106
- APITOGO_CONFIG_SITE__TITLE=My Local Site
107
- APITOGO_CONFIG_PRICING__ENABLED=true
108
- APITOGO_CONFIG_PROJECT_ID=your-local-project-id
109
- APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL=https://your-dev-portal-api.example.com
110
- ```
111
-
112
- Publish secrets (uncomment in `.env`, never commit):
113
-
114
- ```sh
115
- APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
116
- APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
117
- APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
118
- APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
119
- APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
120
- ```
121
-
122
- ## Related
123
-
124
- - [Gateway plans](./plans.md)
125
- - [Authentication](./authentication.md)
126
- - [Overview](./overview.md)
127
- - [MCP overview](../mcp/overview.md)
128
- - [Environment variables](../guides/environment-variables.md)
1
+ # Site configuration (apitogo.config.json)
2
+
3
+ Dev portal sites use `apitogo.config.json` for site settings, plans, authentication, and backend
4
+ metadata, with optional `.env` overrides for secrets and local tweaks.
5
+
6
+ ## Files
7
+
8
+ | File | Purpose |
9
+ | --------------------- | ----------------------------------------------------------- |
10
+ | `apitogo.config.json` | Committed defaults: site, modules, authentication, backend |
11
+ | `.env` | Public client vars + publish secrets via `APITOGO_CONFIG_*` |
12
+
13
+ ## Canonical shape
14
+
15
+ ```json
16
+ {
17
+ "site": {
18
+ "title": "My API",
19
+ "logo": {
20
+ "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
21
+ "alt": "My API",
22
+ "width": "130px"
23
+ }
24
+ },
25
+ "authentication": {
26
+ "enabled": true,
27
+ "type": "dev-portal",
28
+ "apiBaseUrl": "https://your-dev-portal-api.example.com"
29
+ },
30
+ "gateway": {
31
+ "authMode": "bringYourOwnOidc",
32
+ "oidcMetadataUrl": "https://login.example.com/.well-known/openid-configuration",
33
+ "publicRoutes": ["/health"],
34
+ "cors": {
35
+ "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
36
+ }
37
+ },
38
+ "modules": {
39
+ "docs": { "files": "/pages/**/*.{md,mdx}" },
40
+ "landing": { "enabled": true, "path": "/", "layout": "landing" },
41
+ "userPanel": {
42
+ "enabled": true,
43
+ "dashboard": { "enabled": true },
44
+ "userManagement": { "enabled": true },
45
+ "plans": {
46
+ "enabled": true,
47
+ "items": [
48
+ {
49
+ "sku": "free",
50
+ "displayName": "Free",
51
+ "priceAmount": 0
52
+ }
53
+ ]
54
+ }
55
+ }
56
+ },
57
+ "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
58
+ }
59
+ ```
60
+
61
+ - **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
62
+ - **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
63
+ - **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
64
+ `modules.userPanel.plans.items`. Edit the manifest by hand. In a config version 2 project,
65
+ `npx apitogo config` writes plans to `apitogo/plans.json` instead. See
66
+ [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
67
+ - **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
68
+ - **Gateway:** top-level `gateway` (not under `authentication`). See [Gateway CORS](#gateway-cors)
69
+ and [Gateway plans](./plans.md).
70
+
71
+ ## Gateway CORS
72
+
73
+ Browser calls from your developer portal (and any other SPA) to the API gateway are cross-origin.
74
+ APItoGo always allows the portal site origin. Add extra origins under `gateway.cors.allowedOrigins`
75
+ when tenant apps or local frontends call the gateway:
76
+
77
+ ```json
78
+ {
79
+ "gateway": {
80
+ "cors": {
81
+ "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ | Rule | Detail |
88
+ | --------------- | ----------------------------------------------------------------------------------- |
89
+ | Portal origin | Always allowed by the platform (`https://{your-portal-host}`). Do not list it here. |
90
+ | Extra origins | Absolute `http://` or `https://` origins only — no path, query, or fragment. |
91
+ | Wildcard | `"*"` is allowed (replaces the list; credentials stay off). |
92
+ | Empty / omitted | Portal playground still works; only extras are missing. |
93
+
94
+ Apply with `npx apitogo deploy` / `publish_dev_portal` so APIM policies pick up the change.
95
+
96
+ ## Environment variables
97
+
98
+ Public client URL (mirrors `authentication.apiBaseUrl`):
99
+
100
+ ```sh
101
+ VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
102
+ ```
103
+
104
+ Nested config overrides (uppercase SCREAMING_SNAKE path segments; camelCase still accepted):
105
+
106
+ ```sh
107
+ APITOGO_CONFIG_SITE__TITLE=My Local Site
108
+ APITOGO_CONFIG_PRICING__ENABLED=true
109
+ APITOGO_CONFIG_PROJECT_ID=your-local-project-id
110
+ APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL=https://your-dev-portal-api.example.com
111
+ ```
112
+
113
+ Publish secrets (uncomment in `.env`, never commit):
114
+
115
+ ```sh
116
+ APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
117
+ APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
118
+ APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
119
+ APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
120
+ APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
121
+ ```
122
+
123
+ ## Related
124
+
125
+ - [Gateway plans](./plans.md)
126
+ - [Authentication](./authentication.md)
127
+ - [Overview](./overview.md)
128
+ - [MCP overview](../mcp/overview.md)
129
+ - [Environment variables](../guides/environment-variables.md)