@lukoweb/apitogo 0.1.67 → 0.1.69

package/docs/customization/fonts.md

@@ -15,7 +15,7 @@ You can use predefined Google Fonts, external sources, or local fonts.
 The easiest way to use fonts is with predefined Google Fonts. Simply specify the font name as a
 string:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     fonts: {
@@ -44,7 +44,7 @@ Geist Mono
 
 For more control or to use fonts not in the predefined list, you can specify a custom font URL:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     fonts: {
@@ -76,7 +76,7 @@ To use local fonts, add them to the `public` folder and create a `fonts.css` fil
 
 Then reference the local CSS file:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     fonts: {
@@ -93,7 +93,7 @@ const config = {
 
 You can mix predefined fonts with custom fonts:
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   theme: {
     fonts: {

package/docs/deploy/apitogo.md

@@ -1,24 +1,30 @@
 ---
-title: APIToGo
-zuplo: false
+title: Deploy with APIToGo CLI
 ---
 
-[APIToGo](https://app.apitogo.com) gives you a managed way to publish your API documentation without
-having to maintain your own hosting setup.
+[APIToGo](https://apitogo.com) hosts your documentation site. This page covers the **CLI** path
+(`apitogo deploy` with a deployment token).
 
-## Before you deploy
+For a full API product (plans, `dev-portal` auth, gateway, platform Free / Starter / Professional),
+use MCP **`publish_dev_portal`** / `apply_product_intent` mode `goLive` — see
+[MCP go-live](../mcp/go-live.md).
+
+| Path                     | When                                              |
+| ------------------------ | ------------------------------------------------- |
+| MCP `publish_dev_portal` | Connected portal + plans + hosting go-live        |
+| CLI `apitogo deploy`     | Build and upload a site with a deployment token   |
 
-Before publishing, make sure your documentation works locally:
+## Before you deploy
 
 ```bash
 npm run dev
 ```
 
-## Deploy with APIToGo
+## Deploy with the CLI
 
-To publish your docs with APIToGo:
+To publish a site with a deployment token:
 
-1. Sign in to [app.apitogo.com](https://app.apitogo.com)
+1. Sign in to [apitogo.com](https://apitogo.com)
 2. Create a new project or open an existing one
 3. Navigate to Project settings and copy the deployment token
 4. Run the following command:
@@ -78,7 +84,7 @@ request gets a **preview** URL.
 
 ### 1. Generate the workflow
 
-From your documentation project root (the folder that contains `apitogo.config` and `package.json`),
+From your documentation project root (the folder that contains `apitogo.config.json` and `package.json`),
 run:
 
 ```bash
@@ -95,7 +101,7 @@ If the file already exists, pass `--force` to overwrite it.
 
 ### 2. Add your deployment token as a GitHub secret
 
-1. In [APIToGo](https://app.apitogo.com), open your project and copy the **deployment token** from
+1. In [APIToGo](https://apitogo.com), open your project and copy the **deployment token** from
    project settings (the same token you use with `apitogo deploy`).
 2. On GitHub, open your repository → **Settings** → **Secrets and variables** → **Actions**.
 3. Create a new repository secret named **`APITOGO_TOKEN`** and paste the token.
@@ -136,4 +142,4 @@ After your site is live, check the following:
 
 To get started, sign in here:
 
-- [APIToGo Dashboard](https://app.apitogo.com)
+- [APIToGo Dashboard](https://apitogo.com)

package/docs/deploy/cloudflare-pages.md

@@ -1,6 +1,5 @@
 ---
 title: Cloudflare Pages
-zuplo: false
 ---
 
 [Pages](https://developers.cloudflare.com/pages) is a low configuration way of publishing your

package/docs/deploy/direct-upload.md

@@ -1,6 +1,5 @@
 ---
 title: Upload/FTP
-zuplo: false
 ---
 
 APIToGo can produce a build of static HTML, JavaScript and CSS files that you can deploy directly to

package/docs/deploy/github-pages.md

@@ -1,6 +1,5 @@
 ---
 title: GitHub Pages
-zuplo: false
 ---
 
 [GitHub Pages](https://pages.github.com/) is a great way to publish your documentation, especially
@@ -17,7 +16,7 @@ To publish your site to GitHub Pages you will need:
 Use the
 [GitHub Actions Workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow).
 
-You might need to configure the `basePath` in your apitogo.config.ts depending on how your site is
+You might need to configure the `basePath` in your site config.ts depending on how your site is
 hosted. For instance, if your site is available at username.github.io/your-repo/ you would set the
 `basePath` to `/your-repo`.
 

package/docs/deploy/vercel.md

@@ -1,6 +1,5 @@
 ---
 title: Vercel
-zuplo: false
 ---
 
 [Vercel](https://vercel.com) offers multiple ways to deploy to its service, including via GitHub,
@@ -74,8 +73,8 @@ information.
 
 :::caution{title="Redirects"}
 
-If you have redirects configured in your Zuplo configuration, you will need to also add those to
-your `vercel.json` file. See the
+If you have redirects in `apitogo.config.json`, you may also need matching entries in
+`vercel.json`. See the
 [Vercel Configuration](https://vercel.com/docs/projects/project-configuration#redirects) for more
 information.
 

package/docs/deployment.md

@@ -1,21 +1,22 @@
 ---
 title: Deploying APIToGo
-zuplo: false
 ---
 
-Once you are happy with your APIToGo powered documentation and ready to push your docs to production
-you will need to deploy it to your own server, or a hosted service of your choice.
+Choose how you publish:
 
-## Build locally
+| Path | Guide |
+| ---- | ----- |
+| **MCP go-live** (portal + plans + hosting) | [MCP go-live](./mcp/go-live.md) |
+| **CLI** (`apitogo deploy` + token) | [Deploy with APIToGo CLI](./deploy/apitogo.md) |
+| **Static host** (GitHub Pages, upload `dist`) | Below and sibling deploy guides |
 
-APIToGo can produce a build of static HTML, JavaScript and CSS files that you can deploy directly to
-your own server.
+## Build locally
 
-To prepare the files you need to upload to your server, you will need to use the build command.
+Produce static HTML, JavaScript, and CSS for any host:
 
-```
+```bash
 npm run build
 ```
 
-Once complete, you will see a new `dist` folder in the root of your project that includes the files
-you need to upload.
+Output is in `dist/`. Upload that folder, or use [direct upload](./deploy/direct-upload.md) /
+[GitHub Pages](./deploy/github-pages.md).

package/docs/extending/events.md

@@ -48,7 +48,7 @@ const navigationLoggerPlugin: ApitogoPlugin = {
 
 ### Example in APIToGo Config
 
-In your `apitogo.config.ts`, you can define the events like this:
+In your your site config, you can define the events like this:
 
 ```typescript
 export default {

package/docs/guides/custom-pages.md

@@ -47,14 +47,10 @@ export const MyCustomPage = () => {
 
 In the [APIToGo Configuration](../configuration/overview.md) you will need to do the following:
 
-### Change Your Config Extension
+### Config that embeds JSX
 
-In order to embed `jsx`/`tsx` components into your APIToGo config, you will need to change your file
-extension from `ts` to `tsx` (or `js` to `jsx` if not using TypeScript).
-
-```
-apitogo.config.ts -> apitogo.config.tsx
-```
+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
 
@@ -101,6 +97,6 @@ pages, but in case it isn't, it should look like this:
 ```json
 {
   ...
-  "include": ["src", "apitogo.config.tsx", "src/MyCustomPage.tsx"]
+  "include": ["src", "src/MyCustomPage.tsx"]
 }
 ```

package/docs/guides/environment-variables.md

@@ -3,86 +3,77 @@ title: Environment Variables
 sidebar_icon: table
 ---
 
-APIToGo is built on top of Vite and uses [their approach](https://vite.dev/guide/env-and-mode) for
-managing environment variables.
+APIToGo uses Vite’s [env and mode](https://vite.dev/guide/env-and-mode) model, plus
+`APITOGO_CONFIG_*` overrides for `apitogo.config.json`.
 
-APIToGo exposes environment variables under the `import.meta.env` object as strings automatically.
+## Portal / publish (`.env`)
 
-To prevent accidentally leaking environment variables to the client, only variables prefixed with
-`APITOGO_PUBLIC_` are exposed to your APIToGo-processed code.
+| Variable | Purpose |
+| -------- | ------- |
+| `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` | Dev-portal API base URL (client) |
+| `APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` | Same, via config override |
+| `APITOGO_CONFIG_AUTHENTICATION__OIDC__*` | OIDC authority / client id / secret for publish |
+| `APITOGO_CONFIG_AUTHENTICATION__STRIPE__*` | Stripe secret + webhook (paid plans) |
+| `APITOGO_CONFIG_DEMO_MODE` | `false` to disable local demo sign-in |
+| `APITOGO_CONFIG_SITE__TITLE` | Override `site.title` |
+| `APITOGO_CONFIG_PROJECT_ID` | Local project id override |
 
-:::warning{title="Security Notice"}
+Nested overrides use `__` path segments (SCREAMING_SNAKE). See [Manifest](../configuration/manifest.md).
 
-Environment variables prefixed with `APITOGO_PUBLIC_` will be exposed to the client-side code and
-visible in the browser. Never use this prefix for sensitive information like API keys, passwords, or
-other secrets.
+**Never commit** OIDC client secrets or Stripe keys. MCP never puts secrets in chat — you write them
+to `.env` before [go-live](../mcp/go-live.md).
 
-:::
+Example:
 
-## Local Env Files
+```sh
+VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
+APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+```
 
-When developing locally, you can create a `.env` file in the root of your project and add
-environment-specific variables. See the
-[Vite documentation](https://vite.dev/guide/env-and-mode.html#env-files) for more information on
-supported files.
+## Client-visible custom vars (`APITOGO_PUBLIC_*`)
 
-Here is an example of a `.env` file:
+Variables prefixed with `APITOGO_PUBLIC_` are exposed to client code under `import.meta.env`. Do not
+use this prefix for secrets.
 
 ```sh
 APITOGO_PUBLIC_PAGE_TITLE=My Page Title
 ```
 
-You can access this variable in your application like this:
-
 ```ts
 const title = import.meta.env.APITOGO_PUBLIC_PAGE_TITLE;
 ```
 
-## Configuration Files
-
-Environment variables can also be used in your configuration files. When referencing environment
-variables in your configuration files, you can use `process.env` directly.
+In a TSX config you may also read `process.env` for build-time values (SPA providers, etc.):
 
 ```ts
-import type { ApitogoConfig } from "@lukoweb/apitogo";
-
-const config: ApitogoConfig = {
-  authentication: {
-    type: "auth0",
-    clientId: process.env.APITOGO_PUBLIC_AUTH_CLIENT_ID,
-    domain: process.env.APITOGO_PUBLIC_AUTH_DOMAIN,
-  },
-};
+authentication: {
+  type: "auth0",
+  clientId: process.env.APITOGO_PUBLIC_AUTH_CLIENT_ID,
+  domain: process.env.APITOGO_PUBLIC_AUTH_DOMAIN,
+}
 ```
 
-## React Components
+Prefer `dev-portal` + `APITOGO_CONFIG_*` for portal products.
 
-If you need to access environment variables inside a custom react component, you can access them via
-`import.meta.env`. Public environment variables are inlined during the build process.
+## React components
 
 ```tsx
-import React from "react";
-
 export const MyComponent = () => {
   return <h1>{import.meta.env.APITOGO_PUBLIC_PAGE_TITLE}</h1>;
 };
 ```
 
-## IntelliSense for TypeScript
-
-By default, APIToGo provides type definitions for `import.meta.env` in `apitogo/client.d.ts`. While
-you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript
-IntelliSense for user-defined env variables that are prefixed with `APITOGO_PUBLIC_`.
+## TypeScript IntelliSense
 
-To achieve this, you can create an `apitogo-env.d.ts` file in the src directory, then augment
-`ImportMetaEnv` like this:
+Augment `ImportMetaEnv` in a declaration file (no imports in that file):
 
 ```typescript
 /// <reference types="@lukoweb/apitogo/client" />
 
 interface ImportMetaEnv {
   readonly APITOGO_PUBLIC_APP_TITLE: string;
-  // more env variables...
 }
 
 interface ImportMeta {
@@ -90,10 +81,11 @@ interface ImportMeta {
 }
 ```
 
-:::warning{title="Imports will break type augmentation"}
+## MCP host (agent machine)
 
-If the `ImportMetaEnv` augmentation does not work, make sure you do not have any import statements
-in `vite-env.d.ts`. A helpful explanation can be found on
-[this StackOverflow reply](https://stackoverflow.com/a/51114250).
+| Variable | Purpose |
+| -------- | ------- |
+| `APITOGO_API_KEY_ID` / `APITOGO_API_SECRET` | Required for MCP |
+| `APITOGO_DOC_TOOL_PATH` | Optional local doc-tool for scaffold |
 
-:::
+See [MCP overview](../mcp/overview.md).

package/docs/guides/managing-api-keys-and-identities.md

@@ -2,89 +2,75 @@
 title: Managing API Keys and Identities
 sidebar_label: API Keys and Identities
 sidebar_icon: key-square
-zuplo: false
 ---
 
-## Managing API Keys in UI
+## Portal products (APItoGo)
 
-APIToGo comes with a Plugin to manage API keys in the UI. This plugin is build around the concept of
-API consumers, where each consumer can have multiple API keys. It includes functionality for
-creating, viewing, updating, and deleting API keys, as well as managing consumer information.
+For developer portals, enable API keys under **`modules.userPanel.apiKeys`** in
+`apitogo.config.json` (not a root `apiKeys` key):
 
-:::note
-
-The most convenient way to use this plugin is to use it in Zuplo. However the plugin can be used
-with any other API key management system - you can use a 3rd party API key management system or
-build your own and still use the APIToGo UI.
-
-:::
-
-## Using in Zuplo
-
-To get started with a basic setup, simply enable `apiKeys` in your config. (In the default template,
-this is already enabled.)
-
-```typescript title=apitogo.config.ts
+```json
 {
-  // ...
-  apiKeys: {
-    enabled: true,
+  "modules": {
+    "userPanel": {
+      "enabled": true,
+      "apiKeys": { "enabled": true }
+    }
   }
 }
 ```
 
-This will make the API Key UI available at `/settings/api-keys` in your APIToGo.
+With MCP, prefer `update_dev_portal_manifest`. Subscription / gateway keys for provisioned portals
+are issued by the APItoGo platform after sign-in; see [Authentication](../configuration/authentication.md)
+and [MCP go-live](../mcp/go-live.md).
+
+Legacy root `apiKeys: { enabled: true }` is still migrated on load into
+`modules.userPanel.apiKeys`.
 
-### Creating API Keys
+## Custom API key UI plugin
 
-By default, there is no **Create API Key** Button. To get the button working you have to implement
-the `createKey` callback in your config. This callback is called when the user clicks the **Create
-API Key** button. The callback is passed the `apiKey` object that the user has entered, the
-`context` object, and the `auth` object. The `apiKey` object is the object that the user has entered
-in the Create API Key form.
+APIToGo includes a UI plugin for managing API consumers and keys (create, view, update, delete).
+You can point it at any backend by implementing callbacks / `ApiKeyService`.
 
-In this callback you can implement the logic to create a new API key. You can use the `auth` object
-to access the current users auth state. Most likley you want to call your API to create a new API
-key.
+Enable and customize from TSX when you need custom create/list logic:
 
-```typescript title=apitogo.config.ts
+```typescript title=config
 const config = {
-  // ...
   apiKeys: {
     enabled: true,
     createKey: async ({ apiKey, context, auth }) => {
-      const createApiKeyRequest = new Request("https://api.example.com/v1/developer/api-key", {
-        method: "POST",
-        body: JSON.stringify({
-          apiKey,
-        }),
-      });
-
-      // Sign the request using current users Authentication
+      const createApiKeyRequest = new Request(
+        "https://api.example.com/v1/developer/api-key",
+        {
+          method: "POST",
+          body: JSON.stringify({ apiKey }),
+        },
+      );
       const signedRequest = await context.signRequest(createApiKeyRequest);
-
       const response = await fetch(signedRequest);
-
       if (!response.ok) {
         throw new Error("Could not create API Key");
       }
-
       return true;
     },
   },
 };
 ```
 
-## Using with any API Key Management System
+The account UI is typically available under `/account/settings/api-keys` when the user panel is
+enabled.
 
-If you are not using Zuplo's API key management system, you can implement the `ApiKeyService`
-interface to connect to any API key management system.
+## Custom `ApiKeyService`
 
 ```typescript
 interface ApiKeyService {
   getConsumers: (context: ApitogoContext) => Promise<ApiConsumer[]>;
   rollKey?: (consumerId: string, context: ApitogoContext) => Promise<void>;
-  deleteKey?: (consumerId: string, keyId: string, context: ApitogoContext) => Promise<void>;
+  deleteKey?: (
+    consumerId: string,
+    keyId: string,
+    context: ApitogoContext,
+  ) => Promise<void>;
   updateConsumer?: (
     consumer: { id: string; label?: string },
     context: ApitogoContext,
@@ -100,73 +86,12 @@ interface ApiKeyService {
     auth: UseAuthReturn;
   }) => Promise<void>;
 }
-
-interface ApiConsumer {
-  id: string;
-  label: string;
-  keys: ApiKey[];
-}
-
-interface ApiKey {
-  id: string;
-  key: string;
-  description?: string;
-  createdOn: string;
-  expiresOn?: string;
-}
 ```
 
-### Implementing API Key Management
-
-Here's a step-by-step guide to implementing API key management:
+Wire the service through the `apiKeys` config object in TSX (same callbacks as above). Prefer
+`modules.userPanel.apiKeys.enabled` in JSON for portal toggles.
 
-1. First, create a service that implements the `ApiKeyService` interface:
+## Related
 
-```typescript title=apitogo.config.ts
-const config = {
-  // ...
-  apiKeys: {
-    enabled: true,
-
-    // Retrieve all API consumers and their keys
-    getConsumers: async (context) => {
-      // Implement fetching consumers from your storage
-      // Each consumer can have multiple API keys
-      return consumers;
-    },
-
-    // Create a new API key for a consumer
-    createKey: async ({ apiKey, context, auth }) => {
-      const newKey: ApiKey = {
-        id: crypto.randomUUID(),
-        key: `key-${crypto.randomUUID()}`,
-        description: apiKey.description,
-        createdOn: new Date().toISOString(),
-        expiresOn: apiKey.expiresOn,
-      };
-      // Save the new key to your storage
-      // Associate it with the current user/consumer
-    },
-
-    // Delete an API key
-    deleteKey: async (consumerId, keyId, context) => {
-      // Remove the key from the consumer's keys in your storage
-    },
-
-    // Regenerate an API key
-    rollKey: async (consumerId, context) => {
-      // Update the key value for the consumer while maintaining metadata
-    },
-
-    // Update consumer information
-    updateConsumer: async (consumer, context) => {
-      // Update the consumer's label or other metadata
-    },
-
-    // Get API usage statistics (optional)
-    getUsage: async (apiKeys, context) => {
-      // Fetch usage data for the provided API keys
-    },
-  },
-};
-```
+- [Auth providers and API identities](../concepts/auth-provider-api-identities.md)
+- [Manifest](../configuration/manifest.md)

package/docs/guides/navigation-rules.mdx

@@ -22,7 +22,7 @@ customize that generated sidebar without changing the source. You can:
 
 ## Setup
 
-Add a `navigationRules` array to your `apitogo.config.tsx`:
+Add a `navigationRules` array to your `apitogo.config.json`:
 
 ```tsx
 import type { ApitogoConfig } from "@lukoweb/apitogo";

package/docs/guides/processors.mdx

@@ -39,7 +39,7 @@ const buildConfig: ApitogoBuildConfig = {
 
     // Remove extensions based on a custom filter
     removeExtensions({
-      shouldRemove: (key) => key.startsWith("x-zuplo"),
+      shouldRemove: (key) => key.startsWith("x-internal"),
     }),
   ],
 };
@@ -173,7 +173,7 @@ want to split into separate pages.
 Plain strings work out of the box. Version paths and dropdown labels are auto-generated from the
 query parameter values. For more control, use the object form with explicit `path` and `label`.
 
-```ts title=apitogo.config.ts
+```ts title=config
 const config = {
   apis: {
     type: "file",

package/docs/guides/transforming-examples.md

@@ -14,7 +14,7 @@ documentation. This feature is particularly useful when you need to:
 ## Configuration
 
 To use this feature, you need to configure the `transformExamples` function in your
-`apitogo.config.tsx` file. Here's how to do it:
+`apitogo.config.json` file. Here's how to do it:
 
 ```tsx
 import type { ApitogoConfig } from "@lukoweb/apitogo";

package/docs/markdown/code-blocks.md

@@ -117,7 +117,7 @@ function Example() {
 
 ## Configuration
 
-You can configure syntax highlighting in your `apitogo.config.tsx`:
+You can configure syntax highlighting in your `apitogo.config.json`:
 
 :::info
 
@@ -125,7 +125,7 @@ Changes to the syntax `highlighting` configuration require a restart of APIToGo
 
 :::
 
-```tsx {5-15} title=apitogo.config.ts
+```tsx {5-15} title=config
 import { defaultLanguages, type ApitogoConfig } from "@lukoweb/apitogo";
 
 const config: ApitogoConfig = {

package/docs/markdown/mdx.md

@@ -41,7 +41,7 @@ export default function MyCustomComponent() {
 In [APIToGo Configuration](./overview.md) you will need to import the component and add it to the
 `customComponents` option in the configuration.
 
-```ts title=apitogo.config.ts
+```ts title=config
 import MyCustomComponent from "./src/MyCustomComponent";
 
 const config: ApitogoConfig = {