@lukoweb/apitogo 0.2.23 → 0.2.25

package/docs/extending/events.md

@@ -1,124 +1,124 @@
----
-title: Events
-sidebar_icon: shuffle
----
-
-APIToGo provides an events system that allows plugins to react to various application events. This
-system enables you to build dynamic features that respond to user interactions and application state
-changes.
-
-## Available Events
-
-Currently, APIToGo supports the following events:
-
-### location
-
-```typescript
-type LocationEvent = (e: { from?: Location; to: Location }) => void;
-```
-
-Emitted when the user navigates to a different route. Provides both the previous (`from`) and
-current (`to`)
-[Location objects](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) from
-react-router.
-
-Note that the `from` location will be undefined on the initial page load.
-
-## Consuming Events in Plugins
-
-To consume events in your plugin, you can implement the events property in your plugin. This is
-useful for performing actions like sending analytics events or anything else that's not directly
-related to the UI.
-
-```typescript
-import type { ApitogoPlugin } from "@lukoweb/apitogo";
-
-const navigationLoggerPlugin: ApitogoPlugin = {
-  events: {
-    location: ({ from, to }) => {
-      if (!from) {
-        console.log(`Initial navigation to: ${to.pathname}`);
-      } else {
-        console.log(`User navigated from: ${from.pathname} to: ${to.pathname}`);
-      }
-    },
-  },
-};
-```
-
-### Example in APIToGo Config
-
-In your your site config, you can define the events like this:
-
-```typescript
-export default {
-  plugins: [
-    {
-      events: {
-        location: ({ from, to }) => {
-          if (!from) return;
-
-          // E.g. send an analytics event
-          sendAnalyticsEvent({
-            from: from.pathname,
-            to: to.pathname,
-          });
-        },
-      },
-    },
-  ],
-};
-```
-
-## Using Events in Components
-
-APIToGo provides a convenient `useEvent` hook to subscribe to events in your React components. The
-hook can be used in three different ways:
-
-### 1. Getting the Latest Event Data
-
-If you just want to access the latest event data without a callback:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  const locationEvent = useEvent("location");
-  return <div>Current path: {locationEvent?.to.pathname}</div>;
-}
-```
-
-### 2. Using Event Data in a Component
-
-If you want to transform the event data, return a value from the callback:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  const pathname = useEvent("location", ({ to }) => to.pathname);
-  return <div>Current path: {pathname}</div>;
-}
-```
-
-### 3. Using a Callback for Side Effects
-
-If you just want to perform side effects when the event occurs:
-
-```typescript
-import { useEvent } from "@lukoweb/apitogo/hooks";
-
-function MyComponent() {
-  useEvent("location", ({ from, to }) => {
-    if (from) {
-      console.log(`Navigation: ${from.pathname} → ${to.pathname}`);
-    }
-    // No return value needed for side effects
-  });
-
-  return <div>My Component</div>;
-}
-```
-
-The `useEvent` hook automatically handles subscription and cleanup in the React lifecycle, making it
-easy to work with events in your components.
+---
+title: Events
+sidebar_icon: shuffle
+---
+
+APIToGo provides an events system that allows plugins to react to various application events. This
+system enables you to build dynamic features that respond to user interactions and application state
+changes.
+
+## Available Events
+
+Currently, APIToGo supports the following events:
+
+### location
+
+```typescript
+type LocationEvent = (e: { from?: Location; to: Location }) => void;
+```
+
+Emitted when the user navigates to a different route. Provides both the previous (`from`) and
+current (`to`)
+[Location objects](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) from
+react-router.
+
+Note that the `from` location will be undefined on the initial page load.
+
+## Consuming Events in Plugins
+
+To consume events in your plugin, you can implement the events property in your plugin. This is
+useful for performing actions like sending analytics events or anything else that's not directly
+related to the UI.
+
+```typescript
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const navigationLoggerPlugin: ApitogoPlugin = {
+  events: {
+    location: ({ from, to }) => {
+      if (!from) {
+        console.log(`Initial navigation to: ${to.pathname}`);
+      } else {
+        console.log(`User navigated from: ${from.pathname} to: ${to.pathname}`);
+      }
+    },
+  },
+};
+```
+
+### Example in APIToGo Config
+
+In your your site config, you can define the events like this:
+
+```typescript
+export default {
+  plugins: [
+    {
+      events: {
+        location: ({ from, to }) => {
+          if (!from) return;
+
+          // E.g. send an analytics event
+          sendAnalyticsEvent({
+            from: from.pathname,
+            to: to.pathname,
+          });
+        },
+      },
+    },
+  ],
+};
+```
+
+## Using Events in Components
+
+APIToGo provides a convenient `useEvent` hook to subscribe to events in your React components. The
+hook can be used in three different ways:
+
+### 1. Getting the Latest Event Data
+
+If you just want to access the latest event data without a callback:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  const locationEvent = useEvent("location");
+  return <div>Current path: {locationEvent?.to.pathname}</div>;
+}
+```
+
+### 2. Using Event Data in a Component
+
+If you want to transform the event data, return a value from the callback:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  const pathname = useEvent("location", ({ to }) => to.pathname);
+  return <div>Current path: {pathname}</div>;
+}
+```
+
+### 3. Using a Callback for Side Effects
+
+If you just want to perform side effects when the event occurs:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  useEvent("location", ({ from, to }) => {
+    if (from) {
+      console.log(`Navigation: ${from.pathname} → ${to.pathname}`);
+    }
+    // No return value needed for side effects
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+The `useEvent` hook automatically handles subscription and cleanup in the React lifecycle, making it
+easy to work with events in your components.

package/docs/guides/custom-pages.md

@@ -1,110 +1,110 @@
----
-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 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"]
+}
+```

package/docs/guides/environment-variables.md

@@ -1,94 +1,94 @@
----
-title: Environment Variables
-sidebar_icon: table
----
-
-APIToGo uses Vite’s [env and mode](https://vite.dev/guide/env-and-mode) model, plus
-`APITOGO_CONFIG_*` overrides for `apitogo.config.json`.
-
-## Portal / publish (`.env`)
-
-| 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                       |
-
-Nested overrides use `__` path segments (SCREAMING_SNAKE). See
-[Manifest](../configuration/manifest.md).
-
-**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) or `npx apitogo deploy`
-([CLI go-live](../cli/go-live.md)).
-
-Example:
-
-```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
-```
-
-## Client-visible custom vars (`APITOGO_PUBLIC_*`)
-
-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
-```
-
-```ts
-const title = import.meta.env.APITOGO_PUBLIC_PAGE_TITLE;
-```
-
-In a TSX config you may also read `process.env` for build-time values (SPA providers, etc.):
-
-```ts
-authentication: {
-  type: "auth0",
-  clientId: process.env.APITOGO_PUBLIC_AUTH_CLIENT_ID,
-  domain: process.env.APITOGO_PUBLIC_AUTH_DOMAIN,
-}
-```
-
-Prefer `dev-portal` + `APITOGO_CONFIG_*` for portal products.
-
-## React components
-
-```tsx
-export const MyComponent = () => {
-  return <h1>{import.meta.env.APITOGO_PUBLIC_PAGE_TITLE}</h1>;
-};
-```
-
-## TypeScript IntelliSense
-
-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;
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv;
-}
-```
-
-## MCP host (agent machine)
-
-| Variable                                    | Purpose                                                             |
-| ------------------------------------------- | ------------------------------------------------------------------- |
-| `APITOGO_API_KEY_ID` / `APITOGO_API_SECRET` | Required for MCP and CLI deploy/status/teardown                     |
-| `APITOGO_DOC_TOOL_PATH`                     | Optional local doc-tool for scaffold                                |
-| `APITOGO_CLI_PATH`                          | Optional local `@lukoweb/apitogo` / doc-tool checkout for MCP spawn |
-
-See [MCP overview](../mcp/overview.md) and [CLI overview](../cli/overview.md).
+---
+title: Environment Variables
+sidebar_icon: table
+---
+
+APIToGo uses Vite’s [env and mode](https://vite.dev/guide/env-and-mode) model, plus
+`APITOGO_CONFIG_*` overrides for `apitogo.config.json`.
+
+## Portal / publish (`.env`)
+
+| 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                       |
+
+Nested overrides use `__` path segments (SCREAMING_SNAKE). See
+[Manifest](../configuration/manifest.md).
+
+**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) or `npx apitogo deploy`
+([CLI go-live](../cli/go-live.md)).
+
+Example:
+
+```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
+```
+
+## Client-visible custom vars (`APITOGO_PUBLIC_*`)
+
+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
+```
+
+```ts
+const title = import.meta.env.APITOGO_PUBLIC_PAGE_TITLE;
+```
+
+In a TSX config you may also read `process.env` for build-time values (SPA providers, etc.):
+
+```ts
+authentication: {
+  type: "auth0",
+  clientId: process.env.APITOGO_PUBLIC_AUTH_CLIENT_ID,
+  domain: process.env.APITOGO_PUBLIC_AUTH_DOMAIN,
+}
+```
+
+Prefer `dev-portal` + `APITOGO_CONFIG_*` for portal products.
+
+## React components
+
+```tsx
+export const MyComponent = () => {
+  return <h1>{import.meta.env.APITOGO_PUBLIC_PAGE_TITLE}</h1>;
+};
+```
+
+## TypeScript IntelliSense
+
+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;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+## MCP host (agent machine)
+
+| Variable                                    | Purpose                                                             |
+| ------------------------------------------- | ------------------------------------------------------------------- |
+| `APITOGO_API_KEY_ID` / `APITOGO_API_SECRET` | Required for MCP and CLI deploy/status/teardown                     |
+| `APITOGO_DOC_TOOL_PATH`                     | Optional local doc-tool for scaffold                                |
+| `APITOGO_CLI_PATH`                          | Optional local `@lukoweb/apitogo` / doc-tool checkout for MCP spawn |
+
+See [MCP overview](../mcp/overview.md) and [CLI overview](../cli/overview.md).