@lukoweb/apitogo 0.1.24 → 0.1.37

package/docs/components/tooltip.mdx

@@ -0,0 +1,195 @@
+---
+title: Tooltip
+sidebar_icon: info
+---
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  TooltipArrow,
+} from "@lukoweb/apitogo/ui/Tooltip";
+import { Button } from "@lukoweb/apitogo/ui/Button";
+
+A tooltip component built on Radix UI primitives for displaying helpful information on hover or
+focus.
+
+## Import
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  TooltipArrow,
+} from "@lukoweb/apitogo/ui/Tooltip";
+```
+
+## Components
+
+The Tooltip component consists of several sub-components:
+
+- `TooltipProvider` - Provides context for tooltip behavior
+- `Tooltip` - The main container (root)
+- `TooltipTrigger` - Element that triggers the tooltip
+- `TooltipContent` - The tooltip content container
+- `TooltipArrow` - Optional arrow pointing to the trigger
+
+## Basic Usage
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="outline">Hover</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Add to library</p>
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="outline">Hover</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Add to library</p>
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## With Arrow
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="outline">Hover for tooltip with arrow</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Add to library</p>
+      <TooltipArrow />
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="outline">Hover for tooltip with arrow</Button>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>Add to library</p>
+      <TooltipArrow />
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## Different Sides
+
+<TooltipProvider>
+  <div className="flex gap-2">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Top</Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">
+        <p>Top tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Right</Button>
+      </TooltipTrigger>
+      <TooltipContent side="right">
+        <p>Right tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Bottom</Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        <p>Bottom tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Left</Button>
+      </TooltipTrigger>
+      <TooltipContent side="left">
+        <p>Left tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+  </div>
+</TooltipProvider>
+
+```tsx
+<TooltipProvider>
+  <div className="flex gap-2">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Top</Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">
+        <p>Top tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Right</Button>
+      </TooltipTrigger>
+      <TooltipContent side="right">
+        <p>Right tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Bottom</Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        <p>Bottom tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Left</Button>
+      </TooltipTrigger>
+      <TooltipContent side="left">
+        <p>Left tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
+## Global Provider
+
+For multiple tooltips, wrap your app with `TooltipProvider`:
+
+```tsx
+function App() {
+  return <TooltipProvider>{/* Your app content with tooltips */}</TooltipProvider>;
+}
+```
+
+## Features
+
+- **Keyboard Navigation**: Accessible via keyboard focus
+- **Positioning**: Smart positioning to stay within viewport
+- **Delay Control**: Configurable show/hide delays
+- **Animation**: Smooth enter/exit animations
+- **Accessibility**: Full screen reader and keyboard support

package/docs/components/typography.mdx

@@ -0,0 +1,61 @@
+---
+title: Typography
+sidebar_icon: letter-text
+---
+
+import { Typography } from "@lukoweb/apitogo/components";
+
+The Typography component applies consistent prose styling to text content using
+[Tailwind's typography plugin](https://github.com/tailwindlabs/tailwindcss-typography). It
+automatically formats headings, paragraphs, lists, and other text elements with appropriate spacing,
+
+## Import
+
+```tsx
+import { Typography } from "@lukoweb/apitogo/components";
+```
+
+font sizes, and styling that adapts to both light and dark themes.
+
+This component is particularly useful when rendering markdown content or when you need consistent
+text formatting across your documentation.
+
+## Props
+
+```ts
+type TypographyProps = {
+  children: React.ReactNode;
+  className?: string;
+};
+```
+
+## Usage
+
+Wrap any content that needs prose formatting with the Typography component. It will automatically
+style headings, paragraphs, lists, and other text elements:
+
+```tsx
+import { Typography } from "@lukoweb/apitogo/components";
+
+<Typography>
+  <h1>Hello World</h1>
+  <p>This is a paragraph</p>
+  <ul>
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ul>
+</Typography>;
+```
+
+## Example
+
+<Typography>
+  <h1>Hello World</h1>
+  <p>This is a paragraph</p>
+  <ul>
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ul>
+</Typography>

package/docs/concepts/auth-provider-api-identities.md

@@ -0,0 +1,109 @@
+---
+title: Authentication Providers & API Identities
+sidebar_label: Authentication and Identities
+zuplo: false
+---
+
+When building an API documentation portal, you often need to provide a way for users to authenticate
+their API requests. This typically involves managing API keys and different authentication
+identities. However, implementing a secure and user-friendly system for API key management can be
+complex and time-consuming. APIToGo provides a powerful solution to this problem through its API
+Keys and Identities system.
+
+## Authentication Providers and API Identities
+
+:::tip
+
+**Authentication providers** allow your users to sign in to your documentation portal. **API
+Identities** allow your users to authenticate their API requests.
+
+:::
+
+Before diving into API Identities, it's important to understand that APIToGo separates user
+authentication from API authentication. Authentication providers handle how users sign in to your
+documentation portal, while API Identities manage how these users interact with your APIs.
+
+Authentication providers (like Auth0 or custom JWT) handle:
+
+- User authentication for the documentation portal
+- Session management
+- User authorization and access control
+
+This separation allows you to:
+
+- Use different authentication methods for your portal and APIs
+- Manage API access independently of user authentication
+- Support multiple API authentication schemes simultaneously
+
+[Learn more about authentication providers](../configuration/authentication)
+
+## Understanding API Identities
+
+API Identities in APIToGo represent different authentication contexts that can be used to make API
+requests. These could be different environments (production, staging), different authentication
+methods (API key, JWT), or different service accounts.
+
+### The API Identity Interface
+
+```typescript
+interface ApiIdentity {
+  id: string;
+  label: string;
+  authorizeRequest: (request: Request) => Promise<Request> | Request;
+}
+
+interface ApiIdentityPlugin {
+  getIdentities: () => Promise<ApiIdentity[]> | ApiIdentity[];
+}
+```
+
+Each API Identity consists of:
+
+- `id`: A unique identifier for the identity
+- `label`: A human-readable name shown in the UI
+- `authorizeRequest`: A function that modifies requests to include the necessary authentication
+
+## Implementing API Identities
+
+In this example, we'll use Auth0 as our authentication provider and implement an API Identity for a
+demo API.
+
+:::note
+
+This example shows how to implement API Identities in APIToGo. If you're using Zuplo and you are
+using the built-in API Key management system, you don't need to implement this yourself. Zuplo will
+handle API Identities for you.
+
+:::
+
+To add API Identities to your APIToGo configuration, you need to implement the `ApiIdentityPlugin`
+interface. Here's an example:
+
+```typescript
+import { createApiIdentityPlugin } from "@lukoweb/apitogo/plugins";
+
+export default {
+  authentication: {
+    type: "auth0",
+    domain: "my-domain.auth0.com",
+    clientId: "my-client-id",
+  },
+  plugins: [
+    createApiIdentityPlugin({
+      getIdentities: async (context) => [
+        {
+          id: "api-key-one",
+          label: "My API Key",
+          authorizeRequest: (request) => {
+            // We get the access token from the
+            // authentication provider (Auth0) and add it to the request headers
+            return context.authentication?.signRequest(request);
+          },
+        },
+      ],
+    }),
+  ],
+};
+```
+
+When implemented, this identity will appear in the APIToGo playground.

package/docs/configuration/ai-assistants.md

@@ -0,0 +1,65 @@
+---
+title: AI Assistants
+sidebar_icon: bot
+description:
+  Configure which AI assistant integrations appear in dropdown menus across your APIToGo
+  documentation site, including built-in presets and custom providers.
+---
+
+By default, APIToGo shows "Use in Claude" and "Use in ChatGPT" options in dropdown menus on both
+[API reference](./api-reference.md) and [documentation](./docs.md) pages. You can customize this
+behavior using the top-level `aiAssistants` configuration.
+
+## Disable AI Assistants
+
+To remove all AI assistant options:
+
+```ts title=apitogo.config.ts
+const config = {
+  aiAssistants: false,
+  // ...
+};
+```
+
+## Use Only Specific Presets
+
+```ts title=apitogo.config.ts
+const config = {
+  aiAssistants: ["claude"], // Only show Claude
+  // ...
+};
+```
+
+Available presets: `"claude"`, `"chatgpt"`
+
+## Add Custom AI Assistants
+
+You can add custom entries with a label and URL. Use `{pageUrl}` as a placeholder in the URL string,
+or provide a callback for full control:
+
+```ts title=apitogo.config.ts
+const config = {
+  aiAssistants: [
+    "claude", // built-in preset
+    {
+      label: "Open in MyAI",
+      // Simple string with placeholder
+      url: "https://myai.com/?context={pageUrl}",
+    },
+    {
+      label: "Open in CustomAI",
+      // Callback for full control
+      url: ({ pageUrl, type }) => {
+        if (type === "openapi") {
+          return `https://custom.ai/?q=${encodeURIComponent("Explain this API: " + pageUrl)}`;
+        }
+        return `https://custom.ai/?q=${encodeURIComponent("Explain this page: " + pageUrl)}`;
+      },
+    },
+  ],
+  // ...
+};
+```
+
+The callback receives `{ pageUrl: string, type: "docs" | "openapi" }` so you can customize behavior
+per context.

package/docs/configuration/api-catalog.md

@@ -0,0 +1,109 @@
+---
+title: API Catalog
+sidebar_icon: book-open
+---
+
+If you're dealing with multiple APIs and multiple OpenAPI files, the API Catalog comes in handy. It
+creates an overview of all your APIs and lets you organize them into categories and tags.
+
+## Enable API Catalog
+
+The first step to enable the API Catalog, you need to add a `catalogs` object to your APIToGo
+configuration file.
+
+```js title=apitogo.config.ts
+const config = {
+  // ...
+  catalogs: {
+    path: "/catalog",
+    label: "API Catalog",
+  },
+  // ...
+};
+```
+
+You can then add your APIs to the catalog by adding the `categories` property to your API
+configuration.
+
+```js title=apitogo.config.ts
+const config = {
+  // ...
+  apis: [
+    // ...
+    {
+      type: "file",
+      input: "./operational.json",
+      path: "/api-operational",
+      categories: [{ label: "General", tags: ["Operational"] }],
+    },
+    {
+      type: "file",
+      input: "./enduser.json",
+      path: "/api-enduser",
+      categories: [{ label: "General", tags: ["End-User"] }],
+    },
+    {
+      type: "file",
+      input: "./openapi.json",
+      path: "/api-auth",
+      categories: [{ label: "Other", tags: ["Authentication"] }],
+    },
+    // ...
+  ],
+  // ...
+};
+```
+
+## Advanced Configuration
+
+### Select APIs to show in the catalog
+
+You can select which APIs are shown in the catalog by using the `items` property. The `items`
+property is an array of navigation IDs of the APIs you want to show in the catalog.
+
+```js title=apitogo.config.ts
+const config = {
+  // ...
+  catalogs: {
+    path: "/catalog",
+    label: "API Catalog",
+    // Only show the operational API in the catalog
+    items: ["api-operational"],
+  },
+  apis: [
+    // ...
+    {
+      type: "file",
+      input: "./operational.json",
+      path: "/api-operational",
+      categories: [{ label: "General", tags: ["Operational"] }],
+    },
+    {
+      type: "file",
+      input: "./enduser.json",
+      path: "/api-enduser",
+      categories: [{ label: "General", tags: ["End-User"] }],
+    },
+  ],
+  // ...
+};
+```
+
+### Filtering catalog items
+
+You can filter which APIs are shown in the catalog by using the `filterItems` property. The function
+receives the items and context as arguments.
+
+```js title=apitogo.config.ts
+const config = {
+  // ...
+  catalogs: {
+    path: "/catalog",
+    label: "API Catalog",
+    filterItems: (items, { auth: AuthState }) => {
+      return items.filter((items) => items.tags.includes(auth));
+    },
+  },
+  // ...
+};
+```