@lukoweb/apitogo 0.2.56 → 0.2.57

package/docs/guides/environment-variables.md

@@ -1,94 +0,0 @@
----
-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).

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

@@ -1,89 +0,0 @@
----
-title: Managing API Keys and Identities
-sidebar_label: API Keys and Identities
-sidebar_icon: key-square
----
-
-## Portal products (APItoGo)
-
-For developer portals, enable API keys under **`modules.userPanel.apiKeys`** in
-`apitogo.config.json` (not a root `apiKeys` key):
-
-```json
-{
-  "modules": {
-    "userPanel": {
-      "enabled": true,
-      "apiKeys": { "enabled": true }
-    }
-  }
-}
-```
-
-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`.
-
-## Custom API key UI plugin
-
-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`.
-
-Enable and customize from TSX when you need custom create/list logic:
-
-```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 }),
-      });
-      const signedRequest = await context.signRequest(createApiKeyRequest);
-      const response = await fetch(signedRequest);
-      if (!response.ok) {
-        throw new Error("Could not create API Key");
-      }
-      return true;
-    },
-  },
-};
-```
-
-The account UI is typically available under `/account/settings/api-keys` when the user panel is
-enabled.
-
-## 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>;
-  updateConsumer?: (
-    consumer: { id: string; label?: string },
-    context: ApitogoContext,
-  ) => Promise<void>;
-  getUsage?: (apiKeys: string[], context: ApitogoContext) => Promise<void>;
-  createKey?: ({
-    apiKey,
-    context,
-    auth,
-  }: {
-    apiKey: { description: string; expiresOn?: string };
-    context: ApitogoContext;
-    auth: UseAuthReturn;
-  }) => Promise<void>;
-}
-```
-
-Wire the service through the `apiKeys` config object in TSX (same callbacks as above). Prefer
-`modules.userPanel.apiKeys.enabled` in JSON for portal toggles.
-
-## Related
-
-- [Auth providers and API identities](../concepts/auth-provider-api-identities.md)
-- [Manifest](../configuration/manifest.md)

package/docs/guides/navigation-rules.mdx

@@ -1,203 +0,0 @@
----
-title: Navigation Rules
-sidebar_icon: list-tree
----
-
-import {
-  LayersPlusIcon,
-  PencilIcon,
-  SortAscIcon,
-  ArrowUpDownIcon,
-  TrashIcon,
-} from "@lukoweb/apitogo/icons";
-
-Plugins like the OpenAPI plugin generate sidebar navigation automatically. Navigation rules let you
-customize that generated sidebar without changing the source. You can:
-
-- <LayersPlusIcon className="inline-block size-3.5 me-1" /> **Insert** items at a specific position
-- <PencilIcon className="inline-block size-3.5 me-1" /> **Modify** items
-- <SortAscIcon className="inline-block size-3.5 me-1" /> **Sort** items with a custom comparator
-- <ArrowUpDownIcon className="inline-block size-3.5 me-1" /> **Move** items to a different position
-- <TrashIcon className="inline-block size-3.5 me-1" /> **Remove** items
-
-## Setup
-
-Add a `navigationRules` array to your `apitogo.config.json`:
-
-```tsx
-import type { ApitogoConfig } from "@lukoweb/apitogo";
-
-const config: ApitogoConfig = {
-  apis: [{ type: "file", input: "./api.json", path: "api-shipments" }],
-  navigation: [{ type: "link", label: "Shipments", to: "/api-shipments" }],
-  navigationRules: [
-    // rules go here
-  ],
-};
-```
-
-## Inserting docs
-
-Use `type: "insert"` to add items before or after a matched sidebar item. The `match` string uses
-the tab label as the first segment and navigates into the sidebar tree.
-
-```tsx
-navigationRules: [
-  {
-    type: "insert",
-    match: "Shipments/0",
-    position: "before",
-    items: [
-      {
-        type: "doc",
-        file: "api-shipments/getting-started",
-        icon: "plane-takeoff",
-      },
-    ],
-  },
-],
-```
-
-This inserts a "Getting Started" doc before the first item in the Shipments sidebar.
-
-![Inserting a doc before the first sidebar item](./navigation-rules/insert-doc.png)
-
-The MDX file lives at `pages/api-shipments/getting-started.mdx` (under your configured docs
-directory, matching the API's base path).
-
-## Adding links
-
-You can insert external or internal links the same way:
-
-```tsx
-{
-  type: "insert",
-  match: "Shipments/-1",
-  position: "after",
-  items: [
-    {
-      type: "link",
-      label: "System Status",
-      to: "/status",
-      icon: "satellite",
-    },
-  ],
-}
-```
-
-The `-1` index targets the last item, and `position: "after"` places the link at the very end of the
-sidebar.
-
-![Inserting a link after the last sidebar item](./navigation-rules/insert-doc-end.png)
-
-## Modifying items
-
-Use `type: "modify"` to change properties of existing sidebar items like their icon, label, or
-collapsed state:
-
-```tsx
-{
-  type: "modify",
-  match: "Shipments/Shipment Management",
-  set: { icon: "box", collapsed: true },
-}
-```
-
-![Modifying a sidebar item's icon](./navigation-rules/modify-item.png)
-
-## Removing items
-
-`type: "remove"` hides items from the sidebar. This is rarely needed since it's usually better to
-fix the underlying source, but can be useful as a quick workaround:
-
-```tsx
-{
-  type: "remove",
-  match: "Shipments/Deprecated Endpoint",
-}
-```
-
-## Sorting items
-
-Use `type: "sort"` to reorder children of a category alphabetically or with any custom comparator:
-
-```tsx
-{
-  type: "sort",
-  match: "Shipments",
-  by: (a, b) => a.label.localeCompare(b.label),
-}
-```
-
-The `by` function receives two navigation items and works like a standard `Array.sort` comparator.
-
-## Moving items
-
-Use `type: "move"` to relocate an existing item to a different position in the sidebar:
-
-```tsx
-{
-  type: "move",
-  match: "Shipments/Track a Shipment",
-  to: "Shipments/0",
-  position: "before",
-}
-```
-
-This moves "Track a Shipment" to the top of the Shipments category. You can also move items between
-different levels, for example from inside a category to the root level.
-
-## Rule order
-
-Rules are applied sequentially, so order matters. For example, sorting first and then inserting
-places the new item at an exact position in the already-sorted list. Inserting first and then
-sorting will sort the new item along with everything else.
-
-## Complete example
-
-This is the configuration used in the Cosmo Cargo demo shown above:
-
-```tsx
-navigationRules: [
-  {
-    type: "sort",
-    match: "Shipments",
-    by: (a, b) => a.label.localeCompare(b.label),
-  },
-  {
-    type: "insert",
-    match: "Shipments/Shipment",
-    position: "before",
-    items: [
-      {
-        type: "doc",
-        file: "api-shipments/getting-started",
-        icon: "plane-takeoff",
-      },
-    ],
-  },
-  {
-    type: "insert",
-    match: "Shipments/-1",
-    position: "after",
-    items: [
-      {
-        type: "link",
-        label: "System Status",
-        to: "/status",
-        icon: "satellite",
-      },
-    ],
-  },
-  {
-    type: "modify",
-    match: "Shipments/1",
-    set: { icon: "box" },
-  },
-],
-```
-
-## Match syntax reference
-
-For the full match syntax including label matching, index selectors, and nested paths, see the
-[Navigation Rules reference](/docs/configuration/navigation#navigation-rules).

package/docs/guides/processors.mdx

@@ -1,234 +0,0 @@
----
-sidebar_icon: cpu
----
-
-# Schema Processors
-
-Schema processors are functions that transform your OpenAPI schemas before they are used in the
-documentation. They are defined in your `apitogo.build.ts` file and can be used to modify schemas in
-various ways.
-
-:::tip
-
-For information on how to configure processors in your project, see the
-[Build Configuration](../configuration/build-configuration) guide.
-
-:::
-
-## Built-in Processors
-
-APIToGo provides several built-in processors that you can use to transform your schemas:
-
-### `removeExtensions`
-
-Removes OpenAPI extensions (`x-` prefixed properties) from your schema:
-
-```ts
-import { removeExtensions } from "@lukoweb/apitogo/processors/removeExtensions";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove all x- prefixed properties
-    removeExtensions(),
-
-    // Remove specific extensions
-    removeExtensions({
-      keys: ["x-internal", "x-deprecated"],
-    }),
-
-    // Remove extensions based on a custom filter
-    removeExtensions({
-      shouldRemove: (key) => key.startsWith("x-internal"),
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-### `removeParameters`
-
-Removes parameters from your schema:
-
-```ts
-import { removeParameters } from "@lukoweb/apitogo/processors/removeParameters";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove parameters by name
-    removeParameters({
-      names: ["apiKey", "secret"],
-    }),
-
-    // Remove parameters by location
-    removeParameters({
-      in: ["header", "query"],
-    }),
-
-    // Remove parameters based on a custom filter
-    removeParameters({
-      shouldRemove: ({ parameter }) => parameter["x-internal"],
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-### `removePaths`
-
-Removes paths or operations from your schema:
-
-```ts
-import { removePaths } from "@lukoweb/apitogo/processors/removePaths";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove entire paths
-    removePaths({
-      paths: {
-        "/internal": true,
-        "/admin": ["get", "post"],
-      },
-    }),
-
-    // Remove paths based on a custom filter
-    removePaths({
-      shouldRemove: ({ path, method, operation }) => operation["x-internal"],
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-:::info
-
-If you are missing a processor that you think should be built-in, please don't hesitate to
-[open an issue on GitHub](https://github.com/lukoweb/apitogo-doc-tool/issues/new).
-
-:::
-
-## Custom Processors
-
-You can also create your own processors. Here's a simple example that adds a description to all
-operations:
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-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.description = "This is a public API endpoint";
-      }
-    });
-  });
-
-  return schema;
-}
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [addDescriptionProcessor],
-};
-
-export default buildConfig;
-```
-
-### Adding Server URLs
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-async function addServerUrl({ schema }) {
-  return {
-    ...schema,
-    servers: [{ url: "https://api.example.com" }],
-  };
-}
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [addServerUrl],
-};
-
-export default buildConfig;
-```
-
-## Using Query Parameters to Split Schemas
-
-You can use the same OpenAPI file multiple times with different processing by appending query
-parameters to the file input string. These parameters are passed to your processors via the `params`
-argument, allowing you to filter or transform the schema differently for each variant.
-
-This is useful when you have a single schema containing multiple API versions or groups that you
-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=config
-const config = {
-  apis: {
-    type: "file",
-    input: [
-      // Object form: explicit path and label
-      {
-        input: "openapi.json?prefix=/v2",
-        path: "latest",
-        label: "Latest (v2)",
-      },
-      // Object form: explicit path, label auto-generated from params
-      {
-        input: "openapi.json?prefix=/v1.1",
-        path: "v1.1",
-      },
-      // Plain string: both path and label auto-generated from params
-      "openapi.json?prefix=/v1",
-    ],
-    path: "/api",
-  },
-};
-```
-
-```ts title=apitogo.build.ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    ({ schema, params }) => {
-      const prefix = params.prefix;
-      if (!prefix) return schema;
-
-      return {
-        ...schema,
-        paths: Object.fromEntries(
-          Object.entries(schema.paths ?? {}).filter(([path]) => path.startsWith(prefix)),
-        ),
-      };
-    },
-  ],
-};
-
-export default buildConfig;
-```
-
-Each version tab will show only the endpoints matching that prefix. The query parameters are
-arbitrary key-value pairs that you define and consume in your processors.
-
-When schema download is enabled, param variants serve the processed (filtered) schema rather than
-the original file.
-
-## Best Practices
-
-- **Handle missing properties**: Check for the existence of properties before accessing them
-- **Return the schema**: Always return the transformed schema, even if no changes were made
-- **Use async/await**: Processors can be async functions, which is useful for more complex
-  transformations
-- **Chain processors**: Processors are executed in order, so you can chain multiple transformations