@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/authentication.md

@@ -1,159 +1,159 @@
----
-title: Authentication
-sidebar_icon: shield-check
----
-
-API products on APItoGo use **`dev-portal`** authentication: the static site delegates sign-in to
-the provisioned portal API; OIDC client secrets stay on the backend.
-
-For docs-only sites that embed a SPA identity provider directly in the browser, see
-[SPA providers (advanced)](#spa-providers-advanced).
-
-## Dev portal (recommended)
-
-Set authentication in `apitogo.config.json` (enabled by default on new scaffolds):
-
-```json
-{
-  "authentication": {
-    "enabled": true,
-    "type": "dev-portal",
-    "redirectToAfterSignIn": "/account/dashboard",
-    "redirectToAfterSignUp": "/account/dashboard"
-  }
-}
-```
-
-Backend API URL (`npx apitogo deploy` writes this to `.env` after the portal backend is
-provisioned):
-
-```bash
-VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-You do not need to enter this URL in `npx apitogo config`. Or set `authentication.apiBaseUrl` in
-JSON / `APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` in `.env` manually.
-
-### Local demo mode
-
-In development (`npx apitogo run`), `demoMode` is on by default when the user panel is enabled. You
-do not need a backend URL or OIDC to explore account pages. Sign in at `/login` with:
-
-```text
-demo@apitogo.local / password
-```
-
-Disable with `APITOGO_CONFIG_DEMO_MODE=false` or `"demoMode": false` in JSON. Demo mode is never
-active in production builds.
-
-When demo is off and the backend URL is a placeholder, the account area explains that sign-in
-unlocks after publish. Docs and API reference stay public. Plans on `/pricing` come from
-`apitogo.config.json` (see [Manifest](./manifest.md)).
-
-### Config files
-
-| Concern                                 | File                                                         |
-| --------------------------------------- | ------------------------------------------------------------ |
-| Site, plans, modules, branding, backend | `apitogo.config.json` (+ `.env` — [Manifest](./manifest.md)) |
-| OIDC and Stripe for publish             | `.env` via `APITOGO_CONFIG_AUTHENTICATION__*`                |
-
-### Production OIDC
-
-Register one OIDC app with redirect URI `https://{backend}/signin-oidc` (MCP returns
-`manualSteps.oidcRedirectUri` after publish). The frontend uses cookie sessions via
-`credentials: "include"` on `/api/v1/auth/me`.
-
-Publish secrets (site `.env`, never commit):
-
-```sh
-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
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
-```
-
-Stripe is required only when you have **paid** gateway plans. Full flow:
-[MCP go-live](../mcp/go-live.md).
-
-Auth mode for end users (`native` | `oidc` | `nativeAndOidc`) is shaped via MCP /
-`update_dev_portal_manifest`.
-
-## Protected routes
-
-After authentication is configured, protect routes with patterns or callbacks:
-
-```json
-{
-  "protectedRoutes": ["/admin/*", "/settings", "/api/*"]
-}
-```
-
-Or in TSX for custom authorization — see [Protected routes](./protected-routes.md).
-
-## SPA providers (advanced)
-
-:::caution{title="Portal products use dev-portal"}
-
-SPA providers (Auth0, Clerk, OpenID, Supabase, Azure B2C, Firebase, PingFederate) run the OAuth
-callback in the browser (`/oauth/callback`). Prefer **`dev-portal`** for APItoGo-hosted API
-products. Use SPA providers only for standalone docs sites that talk to the IdP directly.
-
-:::
-
-Configure `authentication` in JSON or TSX. Provider-specific pages:
-
-- [Auth0](./authentication-auth0.md)
-- [Clerk](./authentication-clerk.md)
-- [Azure AD / B2C](./authentication-azure-ad.md)
-- [PingFederate](./authentication-pingfederate.md)
-- [Supabase](./authentication-supabase.md)
-- [Firebase](./authentication-firebase.md)
-
-Typical SPA callback setup:
-
-- Production: `https://your-site.com/oauth/callback`
-- Local: `http://localhost:3000/oauth/callback`
-- Add your site hostname to allowed CORS origins in the IdP
-
-### Auth0 (SPA example)
-
-```ts
-authentication: {
-  type: "auth0",
-  domain: "yourdomain.us.auth0.com",
-  clientId: "<your-auth0-clientId>",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-### Clerk (SPA example)
-
-```ts
-authentication: {
-  type: "clerk",
-  clerkPubKey: "<your-clerk-publishable-key>",
-  jwtTemplateName: "dev-portal", // optional
-}
-```
-
-### OpenID (SPA example)
-
-```ts
-authentication: {
-  type: "openid",
-  clientId: "<your-client-id>",
-  issuer: "<the-issuer-url>",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-### Supabase / Azure B2C
-
-See the provider pages for full options. Default scopes are `openid`, `profile`, and `email` unless
-you override them.
-
-## User profile fields
-
-After SPA login, the profile comes from the provider UserInfo endpoint: `name`, `email`, `picture`,
-`email_verified`. Missing fields are left blank. Dev-portal sessions use the portal API instead.
+---
+title: Authentication
+sidebar_icon: shield-check
+---
+
+API products on APItoGo use **`dev-portal`** authentication: the static site delegates sign-in to
+the provisioned portal API; OIDC client secrets stay on the backend.
+
+For docs-only sites that embed a SPA identity provider directly in the browser, see
+[SPA providers (advanced)](#spa-providers-advanced).
+
+## Dev portal (recommended)
+
+Set authentication in `apitogo.config.json` (enabled by default on new scaffolds):
+
+```json
+{
+  "authentication": {
+    "enabled": true,
+    "type": "dev-portal",
+    "redirectToAfterSignIn": "/account/dashboard",
+    "redirectToAfterSignUp": "/account/dashboard"
+  }
+}
+```
+
+Backend API URL (`npx apitogo deploy` writes this to `.env` after the portal backend is
+provisioned):
+
+```bash
+VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
+```
+
+You do not need to enter this URL in `npx apitogo config`. Or set `authentication.apiBaseUrl` in
+JSON / `APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL` in `.env` manually.
+
+### Local demo mode
+
+In development (`npx apitogo run`), `demoMode` is on by default when the user panel is enabled. You
+do not need a backend URL or OIDC to explore account pages. Sign in at `/login` with:
+
+```text
+demo@apitogo.local / password
+```
+
+Disable with `APITOGO_CONFIG_DEMO_MODE=false` or `"demoMode": false` in JSON. Demo mode is never
+active in production builds.
+
+When demo is off and the backend URL is a placeholder, the account area explains that sign-in
+unlocks after publish. Docs and API reference stay public. Plans on `/pricing` come from
+`apitogo.config.json` (see [Manifest](./manifest.md)).
+
+### Config files
+
+| Concern                                 | File                                                         |
+| --------------------------------------- | ------------------------------------------------------------ |
+| Site, plans, modules, branding, backend | `apitogo.config.json` (+ `.env` — [Manifest](./manifest.md)) |
+| OIDC and Stripe for publish             | `.env` via `APITOGO_CONFIG_AUTHENTICATION__*`                |
+
+### Production OIDC
+
+Register one OIDC app with redirect URI `https://{backend}/signin-oidc` (MCP returns
+`manualSteps.oidcRedirectUri` after publish). The frontend uses cookie sessions via
+`credentials: "include"` on `/api/v1/auth/me`.
+
+Publish secrets (site `.env`, never commit):
+
+```sh
+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
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
+```
+
+Stripe is required only when you have **paid** gateway plans. Full flow:
+[MCP go-live](../mcp/go-live.md).
+
+Auth mode for end users (`native` | `oidc` | `nativeAndOidc`) is shaped via MCP /
+`update_dev_portal_manifest`.
+
+## Protected routes
+
+After authentication is configured, protect routes with patterns or callbacks:
+
+```json
+{
+  "protectedRoutes": ["/admin/*", "/settings", "/api/*"]
+}
+```
+
+Or in TSX for custom authorization — see [Protected routes](./protected-routes.md).
+
+## SPA providers (advanced)
+
+:::caution{title="Portal products use dev-portal"}
+
+SPA providers (Auth0, Clerk, OpenID, Supabase, Azure B2C, Firebase, PingFederate) run the OAuth
+callback in the browser (`/oauth/callback`). Prefer **`dev-portal`** for APItoGo-hosted API
+products. Use SPA providers only for standalone docs sites that talk to the IdP directly.
+
+:::
+
+Configure `authentication` in JSON or TSX. Provider-specific pages:
+
+- [Auth0](./authentication-auth0.md)
+- [Clerk](./authentication-clerk.md)
+- [Azure AD / B2C](./authentication-azure-ad.md)
+- [PingFederate](./authentication-pingfederate.md)
+- [Supabase](./authentication-supabase.md)
+- [Firebase](./authentication-firebase.md)
+
+Typical SPA callback setup:
+
+- Production: `https://your-site.com/oauth/callback`
+- Local: `http://localhost:3000/oauth/callback`
+- Add your site hostname to allowed CORS origins in the IdP
+
+### Auth0 (SPA example)
+
+```ts
+authentication: {
+  type: "auth0",
+  domain: "yourdomain.us.auth0.com",
+  clientId: "<your-auth0-clientId>",
+  scopes: ["openid", "profile", "email"],
+}
+```
+
+### Clerk (SPA example)
+
+```ts
+authentication: {
+  type: "clerk",
+  clerkPubKey: "<your-clerk-publishable-key>",
+  jwtTemplateName: "dev-portal", // optional
+}
+```
+
+### OpenID (SPA example)
+
+```ts
+authentication: {
+  type: "openid",
+  clientId: "<your-client-id>",
+  issuer: "<the-issuer-url>",
+  scopes: ["openid", "profile", "email"],
+}
+```
+
+### Supabase / Azure B2C
+
+See the provider pages for full options. Default scopes are `openid`, `profile`, and `email` unless
+you override them.
+
+## User profile fields
+
+After SPA login, the profile comes from the provider UserInfo endpoint: `name`, `email`, `picture`,
+`email_verified`. Missing fields are left blank. Dev-portal sessions use the portal API instead.

package/docs/configuration/build-configuration.mdx

@@ -1,147 +1,147 @@
----
-sidebar_icon: pickaxe
----
-
-# Build Configuration
-
-The `apitogo.build.ts` file allows you to configure build-time settings and processors for your
-APIToGo project. This file is executed during the build process and can be used to transform your
-API schemas before they are used in the documentation.
-
-:::tip{title="Security Note"}
-
-Unlike your site config which runs in both client and server environments, `apitogo.build.ts` runs
-exclusively in Node.js during build time. This means:
-
-- Sensitive operations (like API calls, file system access) can safely be performed
-- No build-time code or data is included in the final client bundle
-- Environment variables and secrets can be safely accessed
-- No browser-specific APIs are available
-
-:::
-
-## File Location
-
-Create a file named `apitogo.build.ts` in the root of your project:
-
-```bash
-your-project/
-├── apitogo.config.json
-├── apitogo.build.ts    # <-- Add this file
-└── ...
-```
-
-## Basic Configuration
-
-Here's a basic example of a build configuration file:
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    async ({ schema }) => {
-      // Transform your schema here
-      return schema;
-    },
-  ],
-  remarkPlugins: [],
-  rehypePlugins: [],
-};
-
-export default buildConfig;
-```
-
-## Configuration Options
-
-### `processors`
-
-An array of functions that transform your API schemas. Each processor receives:
-
-- `file`: The path to the schema file
-- `schema`: The OpenAPI schema object
-- `params`: Query parameters extracted from the input string (see
-  [Splitting Schemas](../guides/processors#using-query-parameters-to-split-schemas))
-- `dereference`: A function to dereference the schema
-
-Processors are executed in order, and each processor receives the output of the previous one.
-
-:::tip
-
-For detailed information about processors and available built-in processors, see the
-[Schema Processors](../guides/processors) guide.
-
-:::
-
-Here's a simple example that adds a description to all operations:
-
-```ts
-async function addDescriptionProcessor({ schema }) {
-  if (!schema.paths) return schema;
-
-  // Add a description to all operations
-  Object.values(schema.paths).forEach((path) => {
-    Object.values(path).forEach((operation) => {
-      if (typeof operation === "object" && operation) {
-        operation.description = "This is a public API endpoint";
-      }
-    });
-  });
-
-  return schema;
-}
-
-export default {
-  processors: [addDescriptionProcessor],
-};
-```
-
-### `remarkPlugins`
-
-An array of [Remark](https://github.com/remarkjs/remark) plugins to transform Markdown content.
-These plugins run before the content is converted to HTML.
-
-```ts
-import remarkContributors from "remark-contributors";
-
-export default {
-  remarkPlugins: [remarkContributors],
-};
-```
-
-### `rehypePlugins`
-
-An array of [Rehype](https://github.com/rehypejs/rehype) plugins to transform HTML content. These
-plugins run after Markdown is converted to HTML.
-
-```ts
-import rehypeKatex from "rehype-katex";
-
-export default {
-  rehypePlugins: [rehypeKatex],
-};
-```
-
-### `prerender`
-
-Configuration for the prerendering process that generates static HTML pages during build time.
-
-- `workers`: Number of parallel workers to use for prerendering. Defaults to 80% of available CPU
-  cores.
-
-```ts
-import os from "node:os";
-
-export default {
-  prerender: {
-    workers: 4, // Fixed number of workers
-  },
-};
-
-// Or use a percentage of available CPU cores
-export default {
-  prerender: {
-    workers: Math.floor(os.cpus().length * 0.75), // Use 75% of available cores
-  },
-};
-```
+---
+sidebar_icon: pickaxe
+---
+
+# Build Configuration
+
+The `apitogo.build.ts` file allows you to configure build-time settings and processors for your
+APIToGo project. This file is executed during the build process and can be used to transform your
+API schemas before they are used in the documentation.
+
+:::tip{title="Security Note"}
+
+Unlike your site config which runs in both client and server environments, `apitogo.build.ts` runs
+exclusively in Node.js during build time. This means:
+
+- Sensitive operations (like API calls, file system access) can safely be performed
+- No build-time code or data is included in the final client bundle
+- Environment variables and secrets can be safely accessed
+- No browser-specific APIs are available
+
+:::
+
+## File Location
+
+Create a file named `apitogo.build.ts` in the root of your project:
+
+```bash
+your-project/
+├── apitogo.config.json
+├── apitogo.build.ts    # <-- Add this file
+└── ...
+```
+
+## Basic Configuration
+
+Here's a basic example of a build configuration file:
+
+```ts
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [
+    async ({ schema }) => {
+      // Transform your schema here
+      return schema;
+    },
+  ],
+  remarkPlugins: [],
+  rehypePlugins: [],
+};
+
+export default buildConfig;
+```
+
+## Configuration Options
+
+### `processors`
+
+An array of functions that transform your API schemas. Each processor receives:
+
+- `file`: The path to the schema file
+- `schema`: The OpenAPI schema object
+- `params`: Query parameters extracted from the input string (see
+  [Splitting Schemas](../guides/processors#using-query-parameters-to-split-schemas))
+- `dereference`: A function to dereference the schema
+
+Processors are executed in order, and each processor receives the output of the previous one.
+
+:::tip
+
+For detailed information about processors and available built-in processors, see the
+[Schema Processors](../guides/processors) guide.
+
+:::
+
+Here's a simple example that adds a description to all operations:
+
+```ts
+async function addDescriptionProcessor({ schema }) {
+  if (!schema.paths) return schema;
+
+  // Add a description to all operations
+  Object.values(schema.paths).forEach((path) => {
+    Object.values(path).forEach((operation) => {
+      if (typeof operation === "object" && operation) {
+        operation.description = "This is a public API endpoint";
+      }
+    });
+  });
+
+  return schema;
+}
+
+export default {
+  processors: [addDescriptionProcessor],
+};
+```
+
+### `remarkPlugins`
+
+An array of [Remark](https://github.com/remarkjs/remark) plugins to transform Markdown content.
+These plugins run before the content is converted to HTML.
+
+```ts
+import remarkContributors from "remark-contributors";
+
+export default {
+  remarkPlugins: [remarkContributors],
+};
+```
+
+### `rehypePlugins`
+
+An array of [Rehype](https://github.com/rehypejs/rehype) plugins to transform HTML content. These
+plugins run after Markdown is converted to HTML.
+
+```ts
+import rehypeKatex from "rehype-katex";
+
+export default {
+  rehypePlugins: [rehypeKatex],
+};
+```
+
+### `prerender`
+
+Configuration for the prerendering process that generates static HTML pages during build time.
+
+- `workers`: Number of parallel workers to use for prerendering. Defaults to 80% of available CPU
+  cores.
+
+```ts
+import os from "node:os";
+
+export default {
+  prerender: {
+    workers: 4, // Fixed number of workers
+  },
+};
+
+// Or use a percentage of available CPU cores
+export default {
+  prerender: {
+    workers: Math.floor(os.cpus().length * 0.75), // Use 75% of available cores
+  },
+};
+```