@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/configuration/authentication-firebase.md

@@ -1,69 +0,0 @@
----
-title: Firebase Setup
-sidebar_label: Firebase
-description:
-  Learn how to set up Firebase Authentication for APIToGo, leveraging Google's secure authentication
-  infrastructure with multiple sign-in providers.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Firebase SPA
-integration only for standalone docs sites that talk to Firebase directly.
-
-:::
-
-Firebase Authentication provides a comprehensive identity solution from Google, supporting
-email/password authentication and federated identity providers like Google, Facebook, Twitter, and
-more. This guide shows you how to integrate Firebase Authentication with your APIToGo documentation
-site.
-
-## Prerequisites
-
-- A Google account to access Firebase Console
-- A Firebase project (free tier available)
-- Basic knowledge of Firebase configuration
-
-## Setup Firebase
-
-1. Go to the [Firebase Console](https://console.firebase.google.com/):
-2. Click **Create a project** (or select an existing project)
-3. Make sure authentication is enabled. Choose your preferred authentication providers.
-4. Configure Authorized Domains, add your domains where the authentication will be used.
-5. **Get Your Firebase Configuration**
-   - Go to **Project settings**
-   - Scroll to **Your apps** section
-   - Click **Add app** → **Web** if you haven't already
-   - Register your app with a nickname
-   - Copy the Firebase configuration object
-
-## Configure APIToGo
-
-Add the Firebase configuration to your [APIToGo configuration file](./overview.md):
-
-```typescript title="config"
-export default {
-  authentication: {
-    type: "firebase",
-    // Replace these with your Firebase project configuration
-    // Get these values from Firebase Console > Project Settings
-    apiKey: "<insert your API key here>",
-    authDomain: "your-domain.firebaseapp.com",
-    projectId: "your-project-id",
-    appId: "1:296819355813:web:91d29f11cac6f073595d4c",
-    // Optional fields
-    storageBucket: "your-project.firebasestorage.app",
-    messagingSenderId: "296819355813",
-    measurementId: "G-12W6TTNR75",
-    // Optional: specify which providers to show in the sign-in UI
-    // Available providers: "google", "github", "facebook", "twitter",
-    // "microsoft", "apple", "yahoo", "password", "phone"
-    // If not specified, all enabled providers in Firebase will be available
-    providers: ["google", "github", "password"],
-    // Optional: configure redirect URLs after authentication
-    redirectToAfterSignIn: "/docs",
-    redirectToAfterSignUp: "/getting-started",
-    redirectToAfterSignOut: "/",
-  },
-};
-```

package/docs/configuration/authentication-pingfederate.md

@@ -1,143 +0,0 @@
----
-title: PingFederate Setup
-sidebar_label: PingFederate
-description:
-  Learn how to set up PingFederate authentication for APIToGo using OpenID Connect for
-  enterprise-grade single sign-on.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use PingFederate
-SPA integration only for standalone docs sites that talk to PingFederate directly.
-
-:::
-
-PingFederate is an enterprise federation server that enables secure single sign-on (SSO) and API
-security for organizations. This guide walks you through integrating PingFederate with APIToGo using
-OpenID Connect.
-
-## Prerequisites
-
-- Access to a PingFederate server (version 9.0 or later recommended)
-- Administrative access to configure OAuth clients in PingFederate
-- Your PingFederate server's base URL
-
-## Setup Steps
-
-<Stepper>
-
-1. **Create an OAuth Client in PingFederate**
-
-   In the PingFederate administrative console:
-   - Navigate to **Applications** → **OAuth** → **Clients**
-   - Click **Add Client**
-   - Configure the client:
-     - **Client ID**: Choose a unique identifier (e.g., `apitogo-docs`)
-     - **Client Authentication**: Select **None (Public Client)**
-     - **Grant Types**: Enable **Authorization Code** and **Refresh Token**
-     - **Redirect URIs**:
-       - Production: `https://your-site.com/oauth/callback`
-       - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
-       - Local Development: `http://localhost:3000/oauth/callback`
-
-2. **Configure OpenID Connect Settings**
-
-   Still in the OAuth client configuration:
-   - Enable **OpenID Connect**
-   - Configure scopes:
-     - Enable `openid`, `profile`, and `email` (minimum required)
-     - Add any custom scopes your organization requires
-   - **ID Token Signing Algorithm**: RS256 (recommended)
-   - **Access Token Manager**: Select or create an appropriate token manager
-   - Save the configuration
-
-3. **Configure APIToGo**
-
-   Add the PingFederate configuration to your [APIToGo configuration file](./overview.md):
-
-   ```typescript
-   // site config
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "openid",
-       clientId: "apitogo-docs", // Your OAuth client ID
-       issuer: "https://pingfederate.your-domain.com", // Your PingFederate base URL
-       scopes: ["openid", "profile", "email"], // Optional: add custom scopes
-     },
-     // ... other configuration
-   };
-   ```
-
-</Stepper>
-
-## Configuration Options
-
-### Custom Scopes
-
-If your organization uses custom scopes for authorization, include them in the configuration:
-
-```typescript
-authentication: {
-  type: "openid",
-  clientId: "apitogo-docs",
-  issuer: "https://pingfederate.your-domain.com",
-  scopes: ["openid", "profile", "email", "groups", "roles", "api:read"],
-}
-```
-
-## Advanced Configuration
-
-### CORS Configuration
-
-Configure CORS in PingFederate for your documentation site:
-
-1. Navigate to **System** → **Server Configuration** → **Cross-Origin Resource Sharing**
-2. Add your site's domain to the allowed origins:
-   - `https://your-site.com`
-   - `http://localhost:3000` (for local development)
-
-### Attribute Mapping
-
-PingFederate can map user attributes from various sources. Ensure these standard claims are mapped:
-
-1. Go to **OAuth** → **Access Token Management** → **Your Token Manager**
-2. Configure attribute mappings:
-   - `sub` → User's unique identifier
-   - `name` → User's display name
-   - `email` → User's email address
-   - `picture` → User's profile picture URL (if available)
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Discovery Endpoint Not Found**: Ensure your issuer URL is correct and accessible. The OpenID
-   Connect discovery endpoint should be available at
-   `https://your-pingfederate-server/.well-known/openid-configuration`.
-
-2. **Invalid Client Configuration**: Verify that the client ID matches exactly and that the redirect
-   URIs are properly configured in PingFederate.
-
-3. **CORS Errors**: Check that your site's domain is added to PingFederate's CORS configuration.
-
-4. **Missing User Attributes**: Ensure attribute mappings are configured in your Access Token
-   Manager.
-
-5. **Token Validation Errors**: Verify that your PingFederate server's certificates are valid and
-   that clock synchronization is accurate.
-
-## Security Considerations
-
-- Always use HTTPS for production deployments
-- Regularly rotate signing certificates in PingFederate
-- Configure appropriate session timeouts
-- Review and audit OAuth client configurations periodically
-
-## Next Steps
-
-- Review [PingFederate documentation](https://docs.pingidentity.com/pingfederate/) for advanced
-  features
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
-- Configure group-based access control using PingFederate claims

package/docs/configuration/authentication-supabase.md

@@ -1,233 +0,0 @@
----
-title: Supabase Setup
-sidebar_label: Supabase
-description:
-  Learn how to set up Supabase authentication for APIToGo, leveraging Supabase's built-in auth
-  providers for secure documentation access.
----
-
-:::caution{title="SPA / advanced"}
-
-Portal products on APItoGo use [`dev-portal`](./authentication.md) authentication. Use Supabase SPA
-integration only for standalone docs sites that talk to Supabase directly.
-
-:::
-
-Supabase is an open-source Firebase alternative that provides authentication, database, and storage
-services. This guide shows you how to integrate Supabase authentication with your APIToGo
-documentation site.
-
-## Prerequisites
-
-You'll need a Supabase project. If you don't have one,
-[create a free Supabase project](https://supabase.com/dashboard) to get started.
-
-## Setup Steps
-
-<Stepper>
-
-1. **Configure Authentication Provider**
-
-   In your [Supabase Dashboard](https://supabase.com/dashboard):
-   - Navigate to **Authentication** → **Providers**
-   - Enable your preferred authentication provider (GitHub, Google, Azure, etc.)
-   - Configure the provider settings:
-     - **Redirect URL**: `https://your-project.supabase.co/auth/v1/callback`
-     - Copy any required credentials (Client ID, Client Secret) from the provider
-
-2. **Get Your Project Credentials**
-
-   From your Supabase project dashboard:
-   - Go to **Settings** → **Data API**
-   - Copy your **Project URL** (looks like `https://your-project.supabase.co`)
-   - Go to **Settings** → **API Keys**
-   - Copy your **anon public** API key
-
-3. **Configure APIToGo**
-
-   Add the Supabase configuration to your [APIToGo configuration file](./overview.md):
-
-   ```ts title="config"
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "supabase",
-       providers: ["github"], // one or more providers
-       supabaseUrl: "https://your-project.supabase.co",
-       supabaseKey: "<your-anon-public-key>",
-     },
-     // ... other configuration
-   };
-   ```
-
-   You can configure multiple providers:
-
-   ```ts title="config"
-   export default {
-     // ... other configuration
-     authentication: {
-       type: "supabase",
-       providers: ["github", "google", "azure"],
-       supabaseUrl: "https://your-project.supabase.co",
-       supabaseKey: "<your-anon-public-key>",
-     },
-     // ... other configuration
-   };
-   ```
-
-4. **Install Supabase Dependencies**
-
-   Add `@supabase/supabase-js` to your project dependencies:
-
-   ```bash
-   npm install @supabase/supabase-js @supabase/auth-ui-shared @supabase/auth-ui-react
-   ```
-
-</Stepper>
-
-## Supported Providers
-
-Supabase supports numerous authentication providers. Use any of these values in the `providers`
-array:
-
-- `apple` - Sign in with Apple
-- `azure` - Microsoft Azure AD
-- `bitbucket` - Bitbucket
-- `discord` - Discord
-- `facebook` - Facebook
-- `figma` - Figma
-- `github` - GitHub
-- `gitlab` - GitLab
-- `google` - Google
-- `kakao` - Kakao
-- `keycloak` - Keycloak
-- `linkedin` / `linkedin_oidc` - LinkedIn
-- `notion` - Notion
-- `slack` / `slack_oidc` - Slack
-- `spotify` - Spotify
-- `twitch` - Twitch
-- `twitter` - Twitter/X
-- `workos` - WorkOS
-- `zoom` - Zoom
-- `fly` - Fly.io
-
-:::info
-
-Email/password authentication does not need to be specified as a provider because it is enabled by
-default in Supabase. To disable email/password authentication and only use OAuth providers, set
-`onlyThirdPartyProviders: true` in your configuration.
-
-:::
-
-## Configuration Options
-
-All available configuration options for Supabase authentication:
-
-```ts title="config"
-authentication: {
-  type: "supabase",
-
-  // Provider configuration (required)
-  // Array of one or more OAuth providers to enable
-  providers: ["google", "github"],
-
-  // Supabase credentials (required)
-  supabaseUrl: "https://your-project.supabase.co",
-  supabaseKey: "<your-anon-public-key>",
-
-  // Optional: Custom base path for auth routes (default: "/")
-  basePath: "/docs",
-
-  // Optional: Disable email/password authentication, only use OAuth providers
-  onlyThirdPartyProviders: true,
-
-  // Optional: Redirect URLs after authentication events
-  redirectToAfterSignUp: "/welcome",
-  redirectToAfterSignIn: "/dashboard",
-  redirectToAfterSignOut: "/",
-}
-```
-
-### Authentication Routes
-
-The Supabase authentication provider automatically creates the following routes:
-
-- `/signin` - Sign in page with configured providers
-- `/signup` - Sign up page with configured providers
-- `/signout` - Sign out endpoint
-
-If you configure a custom `basePath`, these routes will be prefixed with that path (e.g.,
-`/docs/signin`).
-
-## Advanced Configuration
-
-### User Profile Data
-
-APIToGo automatically extracts the following user information from Supabase authentication:
-
-- `sub` - User ID from Supabase
-- `email` - User's email address
-- `name` - User's full name (from `user_metadata.full_name` or `user_metadata.name`)
-- `emailVerified` - Whether the email has been confirmed
-- `pictureUrl` - User's avatar URL (from `user_metadata.avatar_url`)
-
-### Additional User Metadata
-
-To store and access additional user information beyond what's provided by Supabase authentication:
-
-1. Create a `profiles` table in your Supabase database
-2. Set up a database trigger to create profile records on user signup
-3. Use the Supabase client to query this data in your application
-
-Example profile table structure:
-
-```sql
-CREATE TABLE profiles (
-  id UUID REFERENCES auth.users ON DELETE CASCADE,
-  username TEXT UNIQUE,
-  bio TEXT,
-  created_at TIMESTAMPTZ DEFAULT NOW(),
-  PRIMARY KEY (id)
-);
-
--- Create trigger to automatically create profile on user signup
-CREATE OR REPLACE FUNCTION public.handle_new_user()
-RETURNS TRIGGER AS $$
-BEGIN
-  INSERT INTO public.profiles (id)
-  VALUES (new.id);
-  RETURN new;
-END;
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-
-CREATE TRIGGER on_auth_user_created
-  AFTER INSERT ON auth.users
-  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"At least one provider must be provided" Error**: You must configure the `providers` option in
-   your authentication configuration with at least one authentication provider in the array.
-
-2. **Invalid API Key**: Ensure you're using the `anon public` key, not the `service_role` key from
-   your Supabase project settings.
-
-3. **Provider Not Working**: Verify the provider is enabled in your Supabase dashboard and properly
-   configured with the correct redirect URLs.
-
-4. **Redirect URLs**: For local development, update your redirect URLs in both Supabase and the
-   OAuth provider to include `http://localhost:3000`.
-
-5. **CORS Errors**: Check that your site's domain is properly configured in Supabase's allowed URLs
-   under **Authentication** → **URL Configuration**.
-
-6. **Authentication Not Working**: Make sure you have installed all required dependencies:
-   `@supabase/supabase-js`, `@supabase/auth-ui-react`, and `@supabase/auth-ui-shared`.
-
-## Next Steps
-
-- Explore [Supabase Auth documentation](https://supabase.com/docs/guides/auth) for advanced features
-- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation

package/docs/configuration/build-configuration.mdx

@@ -1,147 +0,0 @@
----
-sidebar_icon: pickaxe
----
-
-# Build Configuration
-
-The `apitogo.build.ts` file allows you to configure build-time settings and processors for your
-APIToGo project. This file is executed during the build process and can be used to transform your
-API schemas before they are used in the documentation.
-
-:::tip{title="Security Note"}
-
-Unlike your site config which runs in both client and server environments, `apitogo.build.ts` runs
-exclusively in Node.js during build time. This means:
-
-- Sensitive operations (like API calls, file system access) can safely be performed
-- No build-time code or data is included in the final client bundle
-- Environment variables and secrets can be safely accessed
-- No browser-specific APIs are available
-
-:::
-
-## File Location
-
-Create a file named `apitogo.build.ts` in the root of your project:
-
-```bash
-your-project/
-├── apitogo.config.json
-├── apitogo.build.ts    # <-- Add this file
-└── ...
-```
-
-## Basic Configuration
-
-Here's a basic example of a build configuration file:
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    async ({ schema }) => {
-      // Transform your schema here
-      return schema;
-    },
-  ],
-  remarkPlugins: [],
-  rehypePlugins: [],
-};
-
-export default buildConfig;
-```
-
-## Configuration Options
-
-### `processors`
-
-An array of functions that transform your API schemas. Each processor receives:
-
-- `file`: The path to the schema file
-- `schema`: The OpenAPI schema object
-- `params`: Query parameters extracted from the input string (see
-  [Splitting Schemas](../guides/processors#using-query-parameters-to-split-schemas))
-- `dereference`: A function to dereference the schema
-
-Processors are executed in order, and each processor receives the output of the previous one.
-
-:::tip
-
-For detailed information about processors and available built-in processors, see the
-[Schema Processors](../guides/processors) guide.
-
-:::
-
-Here's a simple example that adds a description to all operations:
-
-```ts
-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) {
-        operation.description = "This is a public API endpoint";
-      }
-    });
-  });
-
-  return schema;
-}
-
-export default {
-  processors: [addDescriptionProcessor],
-};
-```
-
-### `remarkPlugins`
-
-An array of [Remark](https://github.com/remarkjs/remark) plugins to transform Markdown content.
-These plugins run before the content is converted to HTML.
-
-```ts
-import remarkContributors from "remark-contributors";
-
-export default {
-  remarkPlugins: [remarkContributors],
-};
-```
-
-### `rehypePlugins`
-
-An array of [Rehype](https://github.com/rehypejs/rehype) plugins to transform HTML content. These
-plugins run after Markdown is converted to HTML.
-
-```ts
-import rehypeKatex from "rehype-katex";
-
-export default {
-  rehypePlugins: [rehypeKatex],
-};
-```
-
-### `prerender`
-
-Configuration for the prerendering process that generates static HTML pages during build time.
-
-- `workers`: Number of parallel workers to use for prerendering. Defaults to 80% of available CPU
-  cores.
-
-```ts
-import os from "node:os";
-
-export default {
-  prerender: {
-    workers: 4, // Fixed number of workers
-  },
-};
-
-// Or use a percentage of available CPU cores
-export default {
-  prerender: {
-    workers: Math.floor(os.cpus().length * 0.75), // Use 75% of available cores
-  },
-};
-```