@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/configuration/api-catalog.md

@@ -1,109 +0,0 @@
----
-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=config
-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=config
-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=config
-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=config
-const config = {
-  // ...
-  catalogs: {
-    path: "/catalog",
-    label: "API Catalog",
-    filterItems: (items, { auth: AuthState }) => {
-      return items.filter((items) => items.tags.includes(auth));
-    },
-  },
-  // ...
-};
-```

package/docs/configuration/authentication-auth0.md

@@ -1,181 +0,0 @@
----
-title: Auth0 Setup
-sidebar_label: Auth0
-description:
-  Learn how to set up Auth0 authentication for APIToGo, including application configuration and
-  integration steps for secure API documentation access.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Auth0 SPA
-integration only for standalone docs sites that talk to Auth0 directly.
-
-:::
-
-Auth0 is a flexible authentication and authorization platform that integrates seamlessly with
-APIToGo. This guide walks you through setting up Auth0 authentication for your documentation site.
-
-## Prerequisites
-
-If you don't have an Auth0 account, you can sign up for a
-[free Auth0 account](https://auth0.com/signup) that provides 7,000 monthly active users.
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create Auth0 Application**
-
-   [Create a new Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications)
-   in the Auth0 dashboard:
-   - Select type **Single Page Web Applications**
-   - Give your application a descriptive name
-
-2. **Configure Auth0 Application**
-
-   In your Auth0 application settings, configure the following:
-
-   **Application URLs:**
-   - **Allowed Callback URLs**:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
-   - **Allowed Logout URLs**: Same as callback URLs above
-
-   - **Allowed Web Origins**:
-     - Production: `https://your-site.com`
-     - Preview (wildcard): `https://*.your-domain.com`
-     - Local development: `http://localhost:3000`
-
-   **Refresh Token Rotation:**
-   - **Allow Refresh Token Rotation**: Enabled
-   - **Rotation Overlap Period**: 0 seconds (recommended)
-
-   Keep the default **Refresh Token Expiration** settings unless you have specific requirements.
-
-3. Create an Auth0 API:
-   - Navigate to the [APIs section](https://manage.auth0.com/#/apis) in the Auth0 dashboard
-   - Click **Create API**
-   - Set a name (e.g., "APIToGo API") and an identifier (e.g., `https://your-domain.com/api`)
-   - Choose **RS256** as the signing algorithm
-   - Save the API
-
-   :::warning
-
-   This step is important. If you skip creating an API, APIToGo will not be able to validate the
-   tokens issued by Auth0, leading to authentication failures.
-
-   :::
-
-4. **Configure APIToGo**
-
-   Add the Auth0 configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "auth0",
-       domain: "your-domain.us.auth0.com",
-       clientId: "<your-auth0-client-id>",
-       audience: "https://your-domain.com/api", // Your Auth0 API identifier
-     },
-     // ... other configuration
-   };
-   ```
-
-   Where:
-   - **domain**: Your Auth0 domain (found in your application's Basic Information)
-   - **clientId**: The Client ID from your Auth0 application settings
-   - **audience**: The identifier of the Auth0 API you created (e.g., `https://your-domain.com/api`)
-
-</Stepper>
-
-## Advanced Configuration
-
-### Custom Scopes
-
-If you need additional scopes for your API access, you can specify them in the configuration:
-
-```typescript
-authentication: {
-  type: "auth0",
-  domain: "your-domain.us.auth0.com",
-  clientId: "<your-auth0-client-id>",
-  scopes: ["openid", "profile", "email", "read:api", "write:api"],
-}
-```
-
-### Enabling Logout
-
-APIToGo supports logout functionality for Auth0 tenants. For tenants created **on or after November
-14, 2023**, logout is automatically enabled through the OIDC
-[RP-Initiated Logout](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
-endpoint.
-
-To enable logout for your Auth0 application:
-
-1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
-   [Configure Auth0 Application](#setup-steps) above)
-2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
-   production)
-
-For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
-[Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
-for details.
-
-### Customizing the Prompt Parameter
-
-By default, APIToGo sets `prompt="login"` in the Auth0 authorization request, which forces users to
-re-enter their credentials even if they have a valid session. You can customize this behavior using
-the `options.prompt` configuration:
-
-```typescript
-authentication: {
-  type: "auth0",
-  domain: "your-domain.us.auth0.com",
-  clientId: "<your-auth0-client-id>",
-  audience: "https://your-domain.com/api",
-  options: {
-    prompt: "", // Omit the prompt parameter to allow silent authentication
-  },
-}
-```
-
-Valid values for the `prompt` parameter include:
-
-- `"login"` - Force users to re-enter their credentials even if they have a valid session (default)
-- `"consent"` - Force users to consent to authorization even if they previously consented
-- `"select_account"` - Force users to select an account (useful for multi-account scenarios)
-- `"none"` - No prompt is shown; silent authentication only
-- `""` (empty string) - Omit the prompt parameter, allowing Auth0 to handle authentication based on
-  session state
-
-When the prompt parameter is omitted (empty string), Auth0 will:
-
-- Silently authenticate the user if they have a valid session
-- Redirect to the login page if no valid session exists
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Callback URL Mismatch**: Ensure your callback URLs in Auth0 exactly match your site's URL,
-   including the `/oauth/callback` path.
-
-2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
-
-3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
-   trailing slash.
-
-4. **Token Validation Errors**: Ensure the audience in your APIToGo configuration matches the
-   identifier of the Auth0 API you created.
-
-## Next Steps
-
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Explore other [authentication providers](./authentication.md#authentication-providers) supported
-  by APIToGo
-- Configure [user permissions](./authentication.md#user-data) based on Auth0 roles

package/docs/configuration/authentication-azure-ad.md

@@ -1,245 +0,0 @@
----
-title: Azure AD Setup
-sidebar_label: Azure AD
-description:
-  Learn how to set up Azure Active Directory (Microsoft Entra ID) authentication for APIToGo,
-  enabling secure single sign-on for your organization.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Azure AD SPA
-integration only for standalone docs sites that talk to Entra ID directly.
-
-:::
-
-Azure Active Directory (now Microsoft Entra ID) provides enterprise-grade authentication and
-authorization for organizations using Microsoft's cloud identity platform. This guide shows you how
-to integrate Azure AD with your APIToGo documentation site.
-
-## Prerequisites
-
-- An Azure subscription with Azure Active Directory
-- Administrative access to register applications in Azure AD
-- Your Azure AD tenant ID
-
-## Setup Steps
-
-<Stepper>
-
-1. **Register an Application in Azure AD**
-
-   In the [Azure Portal](https://portal.azure.com):
-   - Navigate to **Azure Active Directory** → **App registrations**
-   - Click **New registration**
-   - Configure your application:
-     - **Name**: Enter a descriptive name (e.g., "APIToGo Documentation")
-     - **Supported account types**: Choose based on your needs:
-       - Single tenant (your organization only)
-       - Multitenant (any Azure AD directory)
-       - Multitenant + personal Microsoft accounts
-     - **Redirect URI**:
-       - Platform: **Single-page application (SPA)**
-       - URI: `https://your-site.com/oauth/callback`
-   - Click **Register**
-
-2. **Configure Authentication Settings**
-
-   In your newly registered application:
-   - Go to **Authentication** in the left menu
-   - Under **Single-page application**, add redirect URIs:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
-   - Under **Implicit grant and hybrid flows**:
-     - Enable **ID tokens**
-     - Enable **Access tokens**
-   - Configure **Supported account types** if needed
-   - Save your changes
-
-3. **Configure API Permissions (Optional)**
-
-   If you need specific permissions:
-   - Go to **API permissions**
-   - Click **Add a permission**
-   - Select **Microsoft Graph** → **Delegated permissions**
-   - Add permissions like `User.Read`, `email`, `profile`, `openid`
-   - Grant admin consent if required by your organization
-
-4. **Configure APIToGo**
-
-   Get your application details from the Azure Portal:
-   - Go to **Overview** page of your app registration
-   - Copy the **Application (client) ID**
-   - Copy the **Directory (tenant) ID**
-
-   Add the configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "openid",
-       clientId: "<your-application-client-id>",
-       issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
-       scopes: ["openid", "profile", "email"], // Optional: customize scopes
-     },
-     // ... other configuration
-   };
-   ```
-
-5. **Install Azure AD Dependencies**
-
-   Add `@azure/msal-browser` to your project dependencies:
-
-   ```bash
-   npm install @azure/msal-browser
-   ```
-
-</Stepper>
-
-## Configuration Options
-
-### Single Tenant vs Multitenant
-
-For single tenant (organization-only access):
-
-```typescript
-authentication: {
-  type: "openid",
-  clientId: "<your-application-client-id>",
-  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-For multitenant (any Azure AD organization):
-
-```typescript
-authentication: {
-  type: "openid",
-  clientId: "<your-application-client-id>",
-  issuer: "https://login.microsoftonline.com/common/v2.0",
-  scopes: ["openid", "profile", "email"],
-}
-```
-
-### Custom Scopes and Permissions
-
-Request additional Microsoft Graph API scopes:
-
-```typescript
-authentication: {
-  type: "openid",
-  clientId: "<your-application-client-id>",
-  issuer: "https://login.microsoftonline.com/<your-tenant-id>/v2.0",
-  scopes: [
-    "openid",
-    "profile",
-    "email",
-    "User.Read",
-    "GroupMember.Read.All" // For group-based access control
-  ],
-}
-```
-
-### Protected Routes
-
-Protect specific documentation routes using the `protectedRoutes` configuration:
-
-```typescript
-{
-  // ... other configuration
-  authentication: {
-    type: "openid",
-    // ... Azure AD config
-  },
-  protectedRoutes: [
-    "/api/*",        // Protect all API documentation
-    "/internal/*",   // Protect internal documentation
-    "/admin/*"       // Protect admin sections
-  ],
-}
-```
-
-## Advanced Configuration
-
-### Conditional Access Policies
-
-Azure AD supports conditional access policies that can:
-
-- Require multi-factor authentication
-- Restrict access by location
-- Enforce device compliance
-- Control session lifetime
-
-Configure these in Azure AD Portal under **Security** → **Conditional Access**.
-
-### App Roles and Groups
-
-To implement role-based access control:
-
-1. In your app registration, go to **App roles**
-2. Create custom roles (e.g., "Documentation.Read", "Documentation.Admin")
-3. Assign roles to users or groups in **Enterprise applications**
-4. Access role claims in your application
-
-### B2B Guest Access
-
-To allow external partners access:
-
-1. Enable B2B collaboration in Azure AD
-2. Configure external collaboration settings
-3. Invite guest users to your directory
-4. Grant appropriate permissions to your application
-
-## User Data
-
-Azure AD provides rich user profile data through OpenID Connect:
-
-- `name` - User's display name
-- `email` - User's email address
-- `picture` - Profile picture URL (when available)
-- `email_verified` - Email verification status
-- `preferred_username` - User's UPN (User Principal Name)
-- Additional claims based on your API permissions
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Invalid Client Error**: Ensure the client ID is correct and the application is properly
-   registered.
-
-2. **Redirect URI Mismatch**: The redirect URI must exactly match one configured in Azure AD,
-   including protocol and path.
-
-3. **Tenant Access Issues**: For single-tenant apps, ensure users are from the correct tenant. For
-   multi-tenant, verify the issuer URL uses "common" or "organizations".
-
-4. **Missing User Information**: Check that required API permissions are granted and admin consent
-   is provided if needed.
-
-5. **Token Validation Errors**: Ensure your issuer URL is correct and includes the `/v2.0` endpoint
-   for the Microsoft identity platform.
-
-6. **Authentication Not Working**: Make sure you have installed `@azure/msal-browser` to your
-   project.
-
-## Security Best Practices
-
-- Use single-tenant configuration unless multi-tenant is specifically required
-- Implement conditional access policies for sensitive documentation
-- Regularly review and audit app permissions
-- Monitor sign-in logs in Azure AD for suspicious activity
-- Use app roles for fine-grained access control
-
-## Next Steps
-
-- Explore
-  [Microsoft identity platform documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/)
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Implement
-  [app roles](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps)
-  for advanced authorization

package/docs/configuration/authentication-clerk.md

@@ -1,117 +0,0 @@
----
-title: Clerk Setup
-sidebar_label: Clerk
-description:
-  Learn how to set up Clerk authentication for APIToGo, providing a seamless authentication
-  experience with modern UI components and extensive customization options.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Clerk SPA
-integration only for standalone docs sites that talk to Clerk directly.
-
-:::
-
-Clerk is a modern authentication platform that provides beautiful, customizable UI components and a
-developer-friendly experience. This guide walks you through integrating Clerk authentication with
-your APIToGo documentation site.
-
-## Prerequisites
-
-If you don't have a Clerk account, you can sign up for a [free Clerk account](https://clerk.com/)
-that provides 10,000 monthly active users.
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create a Clerk Application**
-
-   In the [Clerk Dashboard](https://dashboard.clerk.com/):
-   - Click **Create Application**
-   - Enter your application name
-   - Select your preferred authentication methods (email, social providers, etc.)
-   - Click **Create Application**
-
-2. **Create a Clerk JWT Template** You need to create a JWT Template so your JWTs include name,
-   email and email_verified information.
-
-- Navigate to **JWT templates** in the [Clerk Dashboard](https://dashboard.clerk.com/)
-- Create a new template by clicking **Add new template**
-- Pick a name for the template
-- Add the following claims
-  ```json
-  {
-    "name": "{{user.full_name}}",
-    "email": "{{user.primary_email_address}}",
-    "email_verified": "{{user.email_verified}}"
-  }
-  ```
-- Save
-
-3. **Configure APIToGo**
-
-   Get your publishable key from the Clerk dashboard:
-   - Navigate to **API Keys** in your Clerk dashboard
-   - Copy the **Publishable key**
-
-   Use the JWT template name defined in the previous section
-
-   Add the Clerk configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "clerk",
-       clerkPubKey: "<your-clerk-publishable-key>",
-       jwtTemplateName: "<your-clerk-jwt-template-name>",
-     },
-     // ... other configuration
-   };
-   ```
-
-4. **Configure Redirect URLs (Optional)**
-
-   If you need custom redirect behavior, configure the allowed redirect URLs in Clerk:
-   - Go to **Paths** in your Clerk dashboard
-   - Add your production, preview, and local development URLs to the allowed redirect URLs
-   - Common patterns:
-     - Production: `https://your-site.com/oauth/callback`
-     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-     - Local Development: `http://localhost:3000/oauth/callback`
-
-5. **Install Clerk Dependencies**
-
-   Add `@clerk/clerk-js` to your project dependencies:
-
-   ```bash
-   npm install @clerk/clerk-js
-   ```
-
-   </Stepper>
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Invalid Publishable Key**: Ensure you're using the publishable key (starts with `pk_`) and not
-   the secret key.
-
-2. **Authentication Not Working**: Verify that your Clerk application is active and not in
-   development mode when deploying to production.
-
-3. **Redirect Issues**: Check that your domain is added to the allowed redirect URLs in Clerk if
-   using custom redirects.
-
-4. **ReferenceError: can't access lexical declaration 'xxx' before initialization**: Make sure you
-   have installed Clerk to your project.
-
-## Next Steps
-
-- Explore [Clerk's documentation](https://clerk.com/docs) for advanced features
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Configure [user roles and permissions](https://clerk.com/docs/organizations/roles-permissions) in
-  Clerk