@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/protected-routes.md

@@ -1,150 +1,150 @@
----
-title: Protected Routes
-sidebar_icon: squares-subtract
-description:
-  Learn how to protect specific routes in your documentation using authentication, including simple
-  array patterns, advanced authorization with reason codes, and custom callback functions.
----
-
-You can protect specific routes in your documentation by adding the `protectedRoutes` property to
-your [APIToGo configuration](./overview.md). This requires [authentication](./authentication.md) to
-be configured. The property supports two formats: a simple array of path patterns, or an advanced
-object format with custom authorization logic.
-
-:::note{title="Client-side protection only"}
-
-`protectedRoutes` are client-side only. Do not rely on `protectedRoutes` to hide sensitive
-information.
-
-We are working on an additional offering that secures this data server-side.
-
-:::
-
-## Array Format
-
-The simplest way to protect routes is to provide an array of path patterns. Users must be
-authenticated to access these routes.
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: [
-    "/admin/*",     // Protect all routes under /admin
-    "/settings",    // Protect the settings page
-    "/api/*",       // Protect all API-related routes
-    "/private/:id"  // Protect dynamic routes with parameters
-  ],
-  // ...
-}
-```
-
-When a user tries to access a protected route, a login dialog will appear prompting them to sign in
-or register. After logging in, they are automatically redirected back to the route they were trying
-to access.
-
-## Object Format
-
-For more complex authorization logic, you can provide a record mapping route patterns to custom
-callback functions:
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: {
-    // Only allow authenticated users with admin role
-    "/admin/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.role === "admin",
-
-    // Check if user has enterprise access
-    "/api/enterprise/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.subscription === "enterprise",
-
-    // Allow access to beta features based on user attributes
-    "/beta/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.betaAccess === true,
-  },
-  // ...
-}
-```
-
-### Callback Parameters
-
-The callback function receives an object with:
-
-- `auth` - The current authentication state, including `isAuthenticated`, `isPending`, `profile`,
-  and more
-- `context` - The APIToGo context providing access to configuration and utilities
-- `reasonCode` - An object containing the reason code constants `UNAUTHORIZED` and `FORBIDDEN` (see
-  [Reason Codes](#reason-codes))
-
-### Return Values
-
-The callback can return a `boolean` or a reason code string:
-
-| Return value              | Behavior                                          |
-| ------------------------- | ------------------------------------------------- |
-| `true`                    | Allow access to the route                         |
-| `false`                   | Treated as `UNAUTHORIZED` - prompts login         |
-| `reasonCode.UNAUTHORIZED` | Show a login dialog prompting the user to sign in |
-| `reasonCode.FORBIDDEN`    | Show a 403 "Access Denied" page                   |
-
-## Reason Codes
-
-Reason codes allow you to distinguish between users who need to sign in and users who are signed in
-but lack permission. This is useful for building role-based or attribute-based access control.
-
-- **`UNAUTHORIZED`** - The user is not authenticated. A login dialog is shown, and navigation to the
-  route is blocked until the user signs in.
-- **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
-  page is displayed instead of the route content.
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: {
-    // Members-only page: unauthenticated users see a login prompt
-    "/only-members": ({ auth, reasonCode }) =>
-      auth.isAuthenticated ? true : reasonCode.UNAUTHORIZED,
-
-    // VIP page: unauthenticated users see a login prompt,
-    // authenticated users without permission see "Access Denied"
-    "/vip-lounge": ({ auth, reasonCode }) =>
-      !auth.isAuthenticated
-        ? reasonCode.UNAUTHORIZED
-        : auth.profile?.email?.endsWith("@example.com")
-          ? true
-          : reasonCode.FORBIDDEN,
-  },
-  // ...
-}
-```
-
-## Navigation Blocking
-
-When a user navigates to a route that returns `false` or `UNAUTHORIZED`, navigation is intercepted
-before the page changes. The user stays on the current page while a login dialog is displayed. If
-the user cancels, they remain on the current page. If they log in successfully, navigation
-automatically proceeds to the protected route.
-
-Routes that return `FORBIDDEN` do not block navigation — the user navigates to the route and sees
-the "Access Denied" page.
-
-## Path Patterns
-
-The path patterns follow the same syntax as [React Router](https://reactrouter.com):
-
-- `:param` matches a URL segment up to the next `/`, `?`, or `#`
-- `*` matches zero or more characters up to the next `/`, `?`, or `#`
-- `/*` matches all characters after the pattern
-
-For example:
-
-- `/users/:id` matches `/users/123` or `/users/abc`
-- `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
-- `/settings` matches only the exact path `/settings`
-
-## Next Steps
-
-- Learn about [authentication providers](./authentication.md#authentication-providers) supported by
-  APIToGo
-- Configure [user data](./authentication.md#user-data) display
+---
+title: Protected Routes
+sidebar_icon: squares-subtract
+description:
+  Learn how to protect specific routes in your documentation using authentication, including simple
+  array patterns, advanced authorization with reason codes, and custom callback functions.
+---
+
+You can protect specific routes in your documentation by adding the `protectedRoutes` property to
+your [APIToGo configuration](./overview.md). This requires [authentication](./authentication.md) to
+be configured. The property supports two formats: a simple array of path patterns, or an advanced
+object format with custom authorization logic.
+
+:::note{title="Client-side protection only"}
+
+`protectedRoutes` are client-side only. Do not rely on `protectedRoutes` to hide sensitive
+information.
+
+We are working on an additional offering that secures this data server-side.
+
+:::
+
+## Array Format
+
+The simplest way to protect routes is to provide an array of path patterns. Users must be
+authenticated to access these routes.
+
+```typescript title="config"
+{
+  // ...
+  protectedRoutes: [
+    "/admin/*",     // Protect all routes under /admin
+    "/settings",    // Protect the settings page
+    "/api/*",       // Protect all API-related routes
+    "/private/:id"  // Protect dynamic routes with parameters
+  ],
+  // ...
+}
+```
+
+When a user tries to access a protected route, a login dialog will appear prompting them to sign in
+or register. After logging in, they are automatically redirected back to the route they were trying
+to access.
+
+## Object Format
+
+For more complex authorization logic, you can provide a record mapping route patterns to custom
+callback functions:
+
+```typescript title="config"
+{
+  // ...
+  protectedRoutes: {
+    // Only allow authenticated users with admin role
+    "/admin/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.role === "admin",
+
+    // Check if user has enterprise access
+    "/api/enterprise/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.subscription === "enterprise",
+
+    // Allow access to beta features based on user attributes
+    "/beta/*": ({ auth }) =>
+      auth.isAuthenticated && auth.user?.betaAccess === true,
+  },
+  // ...
+}
+```
+
+### Callback Parameters
+
+The callback function receives an object with:
+
+- `auth` - The current authentication state, including `isAuthenticated`, `isPending`, `profile`,
+  and more
+- `context` - The APIToGo context providing access to configuration and utilities
+- `reasonCode` - An object containing the reason code constants `UNAUTHORIZED` and `FORBIDDEN` (see
+  [Reason Codes](#reason-codes))
+
+### Return Values
+
+The callback can return a `boolean` or a reason code string:
+
+| Return value              | Behavior                                          |
+| ------------------------- | ------------------------------------------------- |
+| `true`                    | Allow access to the route                         |
+| `false`                   | Treated as `UNAUTHORIZED` - prompts login         |
+| `reasonCode.UNAUTHORIZED` | Show a login dialog prompting the user to sign in |
+| `reasonCode.FORBIDDEN`    | Show a 403 "Access Denied" page                   |
+
+## Reason Codes
+
+Reason codes allow you to distinguish between users who need to sign in and users who are signed in
+but lack permission. This is useful for building role-based or attribute-based access control.
+
+- **`UNAUTHORIZED`** - The user is not authenticated. A login dialog is shown, and navigation to the
+  route is blocked until the user signs in.
+- **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
+  page is displayed instead of the route content.
+
+```typescript title="config"
+{
+  // ...
+  protectedRoutes: {
+    // Members-only page: unauthenticated users see a login prompt
+    "/only-members": ({ auth, reasonCode }) =>
+      auth.isAuthenticated ? true : reasonCode.UNAUTHORIZED,
+
+    // VIP page: unauthenticated users see a login prompt,
+    // authenticated users without permission see "Access Denied"
+    "/vip-lounge": ({ auth, reasonCode }) =>
+      !auth.isAuthenticated
+        ? reasonCode.UNAUTHORIZED
+        : auth.profile?.email?.endsWith("@example.com")
+          ? true
+          : reasonCode.FORBIDDEN,
+  },
+  // ...
+}
+```
+
+## Navigation Blocking
+
+When a user navigates to a route that returns `false` or `UNAUTHORIZED`, navigation is intercepted
+before the page changes. The user stays on the current page while a login dialog is displayed. If
+the user cancels, they remain on the current page. If they log in successfully, navigation
+automatically proceeds to the protected route.
+
+Routes that return `FORBIDDEN` do not block navigation — the user navigates to the route and sees
+the "Access Denied" page.
+
+## Path Patterns
+
+The path patterns follow the same syntax as [React Router](https://reactrouter.com):
+
+- `:param` matches a URL segment up to the next `/`, `?`, or `#`
+- `*` matches zero or more characters up to the next `/`, `?`, or `#`
+- `/*` matches all characters after the pattern
+
+For example:
+
+- `/users/:id` matches `/users/123` or `/users/abc`
+- `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
+- `/settings` matches only the exact path `/settings`
+
+## Next Steps
+
+- Learn about [authentication providers](./authentication.md#authentication-providers) supported by
+  APIToGo
+- Configure [user data](./authentication.md#user-data) display

package/docs/configuration/search.md

@@ -1,164 +1,164 @@
----
-title: Search
-sidebar_icon: search-code
-description:
-  Learn how to configure and customize search functionality in APIToGo, including setup instructions
-  for Pagefind and Inkeep providers, result transformation, and ranking options.
----
-
-APIToGo offers search functionality that enhances user experience by enabling content discovery
-across your site. When configured, a search bar will appear in the header, allowing users to quickly
-find relevant information on any page.
-
-We currently support three search providers:
-
-- [Pagefind](https://pagefind.app/)
-- [Algolia DocSearch](https://docsearch.algolia.com/)
-- [Inkeep](https://inkeep.com/)
-
-## Pagefind
-
-[Pagefind](https://pagefind.app/) is a lightweight, static search library that can be used to add
-search to your APIToGo site without any external services.
-
-To enable pagefind search, configure the `search` option in your configuration:
-
-```typescript
-{
-  search: {
-    type: "pagefind",
-    // Optional: Maximum number of sub results per page
-    maxSubResults: 3,
-    // Optional: Configure search result ranking (defaults shown below)
-    ranking: {
-      termFrequency: 0.8,
-      pageLength: 0.6,
-      termSimilarity: 1.2,
-      termSaturation: 1.2,
-    },
-  }
-}
-```
-
-### Transforming/Filtering Search Results
-
-You can transform or filter search results using the `transformResults` option. This function
-receives the search result along with the current auth state and context, allowing you to:
-
-- Filter results based on user permissions
-- Modify result content
-- Add custom results
-
-The type of `result` is the same as
-[the type returned by Pagefind's search API](https://github.com/Pagefind/pagefind/blob/03552d041d9533b09563f6c50466b25d394ece64/pagefind_web_js/types/index.d.ts#L123-L160).
-
-```typescript
-{
-  search: {
-    type: "pagefind",
-    transformResults: ({ result, auth, context }) => {
-      // Return false to filter out the result
-      if (!auth.isAuthenticated) return false;
-
-      // Return true or undefined to keep the original result
-      if (result.url.includes("/private/")) return true;
-
-      // Return a modified result
-      return {
-        ...result,
-        title: `${result.title} (${context.meta.title})`
-      };
-    }
-  }
-}
-```
-
-For more information about how Pagefind's ranking system works and how to customize it for your
-content, see the [Pagefind ranking documentation](https://pagefind.app/docs/ranking/).
-
-## Algolia DocSearch
-
-[Algolia DocSearch](https://docsearch.algolia.com/) is a free search solution for open-source
-documentation sites. You can apply for the free DocSearch program or use your own Algolia account.
-
-### Installation
-
-```bash
-npm install @zudoku/plugin-search-algolia
-```
-
-The published package name is still `@zudoku/plugin-search-algolia` (APIToGo Algolia search plugin).
-Add it via the `plugins` array in your site config.
-
-### Configuration
-
-```typescript
-import { algoliaSearchPlugin } from "@zudoku/plugin-search-algolia";
-
-export default {
-  plugins: [
-    algoliaSearchPlugin({
-      appId: "YOUR_APP_ID",
-      apiKey: "YOUR_SEARCH_API_KEY",
-      indices: ["YOUR_INDEX_NAME"],
-    }),
-  ],
-};
-```
-
-You can get your credentials by [applying for DocSearch](https://docsearch.algolia.com/apply/) or
-creating an index through the [Algolia dashboard](https://www.algolia.com/dashboard).
-
-Any additional [DocSearch options](https://docsearch.algolia.com/docs/api/) can be passed alongside
-the required fields.
-
-## Inkeep
-
-[Inkeep](https://inkeep.com/) is an AI-powered search and chat platform that can index your
-documentation and provide intelligent search capabilities to your users.
-
-### Setting up Inkeep Integration
-
-Before you can use Inkeep search in your APIToGo site, you need to set up an Inkeep integration and
-have your site indexed. Here's how to get started:
-
-#### 1. Create an Inkeep Account
-
-1. Go to [Inkeep](https://inkeep.com/) and sign up for an account
-2. Navigate to the [Inkeep Portal](https://portal.inkeep.com/)
-
-#### 2. Set up Site Indexing
-
-1. In the Inkeep Portal, create a new project or integration
-2. Configure your site URL so Inkeep can crawl and index your documentation
-3. Ensure your APIToGo site is deployed and publicly accessible for indexing
-4. Wait for Inkeep to crawl and index your site content (this may take some time)
-
-#### 3. Get Your Integration Credentials
-
-To add Inkeep search to your site you will need to copy some variables from your
-[Inkeep account setting](https://portal.inkeep.com/):
-
-- API Key
-- Integration ID
-- Organization ID
-
-#### 4. Configure APIToGo
-
-Once you have your credentials and your site is indexed, you can configure the `search` option in
-your [APIToGo Configuration](./overview.md):
-
-```typescript
-{
-  // ...
-  search: {
-    type: "inkeep",
-    apiKey: "<your-api-key>",
-    integrationId: "<your-integration-id>",
-    organizationId: "<your-organization-id>",
-    primaryBrandColor: "#26D6FF",
-    organizationDisplayName: "Your Organization Name",
-  }
-  // ...
-}
-```
+---
+title: Search
+sidebar_icon: search-code
+description:
+  Learn how to configure and customize search functionality in APIToGo, including setup instructions
+  for Pagefind and Inkeep providers, result transformation, and ranking options.
+---
+
+APIToGo offers search functionality that enhances user experience by enabling content discovery
+across your site. When configured, a search bar will appear in the header, allowing users to quickly
+find relevant information on any page.
+
+We currently support three search providers:
+
+- [Pagefind](https://pagefind.app/)
+- [Algolia DocSearch](https://docsearch.algolia.com/)
+- [Inkeep](https://inkeep.com/)
+
+## Pagefind
+
+[Pagefind](https://pagefind.app/) is a lightweight, static search library that can be used to add
+search to your APIToGo site without any external services.
+
+To enable pagefind search, configure the `search` option in your configuration:
+
+```typescript
+{
+  search: {
+    type: "pagefind",
+    // Optional: Maximum number of sub results per page
+    maxSubResults: 3,
+    // Optional: Configure search result ranking (defaults shown below)
+    ranking: {
+      termFrequency: 0.8,
+      pageLength: 0.6,
+      termSimilarity: 1.2,
+      termSaturation: 1.2,
+    },
+  }
+}
+```
+
+### Transforming/Filtering Search Results
+
+You can transform or filter search results using the `transformResults` option. This function
+receives the search result along with the current auth state and context, allowing you to:
+
+- Filter results based on user permissions
+- Modify result content
+- Add custom results
+
+The type of `result` is the same as
+[the type returned by Pagefind's search API](https://github.com/Pagefind/pagefind/blob/03552d041d9533b09563f6c50466b25d394ece64/pagefind_web_js/types/index.d.ts#L123-L160).
+
+```typescript
+{
+  search: {
+    type: "pagefind",
+    transformResults: ({ result, auth, context }) => {
+      // Return false to filter out the result
+      if (!auth.isAuthenticated) return false;
+
+      // Return true or undefined to keep the original result
+      if (result.url.includes("/private/")) return true;
+
+      // Return a modified result
+      return {
+        ...result,
+        title: `${result.title} (${context.meta.title})`
+      };
+    }
+  }
+}
+```
+
+For more information about how Pagefind's ranking system works and how to customize it for your
+content, see the [Pagefind ranking documentation](https://pagefind.app/docs/ranking/).
+
+## Algolia DocSearch
+
+[Algolia DocSearch](https://docsearch.algolia.com/) is a free search solution for open-source
+documentation sites. You can apply for the free DocSearch program or use your own Algolia account.
+
+### Installation
+
+```bash
+npm install @zudoku/plugin-search-algolia
+```
+
+The published package name is still `@zudoku/plugin-search-algolia` (APIToGo Algolia search plugin).
+Add it via the `plugins` array in your site config.
+
+### Configuration
+
+```typescript
+import { algoliaSearchPlugin } from "@zudoku/plugin-search-algolia";
+
+export default {
+  plugins: [
+    algoliaSearchPlugin({
+      appId: "YOUR_APP_ID",
+      apiKey: "YOUR_SEARCH_API_KEY",
+      indices: ["YOUR_INDEX_NAME"],
+    }),
+  ],
+};
+```
+
+You can get your credentials by [applying for DocSearch](https://docsearch.algolia.com/apply/) or
+creating an index through the [Algolia dashboard](https://www.algolia.com/dashboard).
+
+Any additional [DocSearch options](https://docsearch.algolia.com/docs/api/) can be passed alongside
+the required fields.
+
+## Inkeep
+
+[Inkeep](https://inkeep.com/) is an AI-powered search and chat platform that can index your
+documentation and provide intelligent search capabilities to your users.
+
+### Setting up Inkeep Integration
+
+Before you can use Inkeep search in your APIToGo site, you need to set up an Inkeep integration and
+have your site indexed. Here's how to get started:
+
+#### 1. Create an Inkeep Account
+
+1. Go to [Inkeep](https://inkeep.com/) and sign up for an account
+2. Navigate to the [Inkeep Portal](https://portal.inkeep.com/)
+
+#### 2. Set up Site Indexing
+
+1. In the Inkeep Portal, create a new project or integration
+2. Configure your site URL so Inkeep can crawl and index your documentation
+3. Ensure your APIToGo site is deployed and publicly accessible for indexing
+4. Wait for Inkeep to crawl and index your site content (this may take some time)
+
+#### 3. Get Your Integration Credentials
+
+To add Inkeep search to your site you will need to copy some variables from your
+[Inkeep account setting](https://portal.inkeep.com/):
+
+- API Key
+- Integration ID
+- Organization ID
+
+#### 4. Configure APIToGo
+
+Once you have your credentials and your site is indexed, you can configure the `search` option in
+your [APIToGo Configuration](./overview.md):
+
+```typescript
+{
+  // ...
+  search: {
+    type: "inkeep",
+    apiKey: "<your-api-key>",
+    integrationId: "<your-integration-id>",
+    organizationId: "<your-organization-id>",
+    primaryBrandColor: "#26D6FF",
+    organizationDisplayName: "Your Organization Name",
+  }
+  // ...
+}
+```