@mehdad67/apitogo 0.1.24

package/docs/deploy/github-pages.md

@@ -0,0 +1,50 @@
+---
+title: GitHub Pages
+zuplo: false
+---
+
+[GitHub Pages](https://pages.github.com/) is a great way to publish your documentation, especially
+if you are using GitHub for source control.
+
+## Prerequisites
+
+To publish your site to GitHub Pages you will need:
+
+- A GitHub account
+
+## Deploying to GitHub Pages
+
+Use the
+[GitHub Actions Workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow).
+
+You might need to configure the `basePath` in your apitogo.config.ts depending on how your site is
+hosted. For instance, if your site is available at username.github.io/your-repo/ you would set the
+`basePath` to `/your-repo`.
+
+```typescript
+import type { ApitogoConfig } from "@lukoweb/apitogo";
+
+const config: ApitogoConfig = {
+  basePath: "/your-repo",
+  //...
+};
+```
+
+## Accurate Last Modified Dates
+
+If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,
+APIToGo automatically tracks the last modified date of your documentation pages using Git history.
+However, GitHub Actions performs shallow clones by default, which can result in inaccurate "Last
+Modified" dates for pages that haven't been updated recently.
+
+To ensure accurate last modified dates, configure the `actions/checkout` step to fetch the full
+history:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # Fetch all history for all branches and tags
+```
+
+For more details, see the
+[actions/checkout documentation](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches).

package/docs/deploy/vercel.md

@@ -0,0 +1,103 @@
+---
+title: Vercel
+zuplo: false
+---
+
+[Vercel](https://vercel.com) offers multiple ways to deploy to its service, including via GitHub,
+and their CLI. You can read more about them in their
+[Deployments Overview](https://vercel.com/docs/deployments/overview).
+
+## Prerequisites
+
+To deploy to Vercel you will need:
+
+- A Vercel account (free)
+- A GitHub account (if deploying via GitHub)
+- The Vercel CLI
+
+Deploying your APIToGo powered documentation using the Vercel CLI is what we will cover in this
+guide.
+
+## Install the CLI
+
+To get started you need to install the CLI:
+
+```bash
+npm i -g vercel
+```
+
+## Setup a new project
+
+Next, set up a new Vercel project in the root of your docs:
+
+```bash
+vercel
+```
+
+This command will set up everything that is needed to deploy your documentation to Vercel.
+
+It will ask some specific questions including the project name and where the code is located. You
+can answer however you like for these.
+
+When you get to this step:
+
+```ansi
+No framework detected. Default Project Settings:
+- Build Command: `npm run vercel-build` or `npm run build`
+- Development Command: None
+- Install Command: `yarn install`, `pnpm install`, `npm install`, or `bun install`
+- Output Directory: `public` if it exists, or `.`
+? Want to modify these settings? (y/N)
+```
+
+Answer _Yes_ and select to modify the Output Directory.
+
+By default Vercel looks for a directory named `public`, but the APIToGo build will be found in
+`dist`. Set the output directory like this:
+
+```ansi
+? What's your Output Directory? dist
+```
+
+After this is complete, your site will build and Vercel will respond with the URL for you to test
+it.
+
+:::tip{title="Clean URLs"}
+
+You will almost certainly want to enable clean URLs for your site. This will remove the `.html`
+extension from your URLs. You can do this by adding a `cleanUrls` property to your `vercel.json`
+file. See the
+[Vercel Configuration](https://vercel.com/docs/projects/project-configuration#cleanurls) for more
+information.
+
+:::
+
+:::caution{title="Redirects"}
+
+If you have redirects configured in your Zuplo configuration, you will need to also add those to
+your `vercel.json` file. See the
+[Vercel Configuration](https://vercel.com/docs/projects/project-configuration#redirects) for more
+information.
+
+This is a current limitation. See [#115](https://github.com/lukoweb/apitogo-doc-tool/issues/151).
+
+:::
+
+## Accurate Last Modified Dates
+
+If you have enabled the [`showLastModified`](/docs/configuration/docs#showlastmodified) option,
+APIToGo automatically tracks the last modified date of your documentation pages using Git history.
+However, Vercel performs shallow clones by default (only fetching the last 10 commits), which can
+result in inaccurate "Last Modified" dates for pages that haven't been updated recently.
+
+To ensure accurate last modified dates, add the `VERCEL_DEEP_CLONE` environment variable to your
+Vercel project:
+
+1. Go to your project settings in Vercel
+2. Navigate to "Environment Variables"
+3. Add a new variable: `VERCEL_DEEP_CLONE=true`
+4. Save and redeploy your site
+
+This will enable full Git history during builds, ensuring all pages show their correct last modified
+dates. The impact on build time is minimal (typically 5-20 seconds on the first build), and
+subsequent builds benefit from caching.

package/docs/deployment.md

@@ -0,0 +1,21 @@
+---
+title: Deploying APIToGo
+zuplo: false
+---
+
+Once you are happy with your APIToGo powered documentation and ready to push your docs to production
+you will need to deploy it to your own server, or a hosted service of your choice.
+
+## Build locally
+
+APIToGo can produce a build of static HTML, JavaScript and CSS files that you can deploy directly to
+your own server.
+
+To prepare the files you need to upload to your server, you will need to use the build command.
+
+```
+npm run build
+```
+
+Once complete, you will see a new `dist` folder in the root of your project that includes the files
+you need to upload.

package/docs/extending/events.md

@@ -0,0 +1,124 @@
+---
+title: Events
+sidebar_icon: shuffle
+---
+
+APIToGo provides an events system that allows plugins to react to various application events. This
+system enables you to build dynamic features that respond to user interactions and application state
+changes.
+
+## Available Events
+
+Currently, APIToGo supports the following events:
+
+### location
+
+```typescript
+type LocationEvent = (e: { from?: Location; to: Location }) => void;
+```
+
+Emitted when the user navigates to a different route. Provides both the previous (`from`) and
+current (`to`)
+[Location objects](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) from
+react-router.
+
+Note that the `from` location will be undefined on the initial page load.
+
+## Consuming Events in Plugins
+
+To consume events in your plugin, you can implement the events property in your plugin. This is
+useful for performing actions like sending analytics events or anything else that's not directly
+related to the UI.
+
+```typescript
+import type { ApitogoPlugin } from "@lukoweb/apitogo";
+
+const navigationLoggerPlugin: ApitogoPlugin = {
+  events: {
+    location: ({ from, to }) => {
+      if (!from) {
+        console.log(`Initial navigation to: ${to.pathname}`);
+      } else {
+        console.log(`User navigated from: ${from.pathname} to: ${to.pathname}`);
+      }
+    },
+  },
+};
+```
+
+### Example in APIToGo Config
+
+In your `apitogo.config.ts`, you can define the events like this:
+
+```typescript
+export default {
+  plugins: [
+    {
+      events: {
+        location: ({ from, to }) => {
+          if (!from) return;
+
+          // E.g. send an analytics event
+          sendAnalyticsEvent({
+            from: from.pathname,
+            to: to.pathname,
+          });
+        },
+      },
+    },
+  ],
+};
+```
+
+## Using Events in Components
+
+APIToGo provides a convenient `useEvent` hook to subscribe to events in your React components. The
+hook can be used in three different ways:
+
+### 1. Getting the Latest Event Data
+
+If you just want to access the latest event data without a callback:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  const locationEvent = useEvent("location");
+  return <div>Current path: {locationEvent?.to.pathname}</div>;
+}
+```
+
+### 2. Using Event Data in a Component
+
+If you want to transform the event data, return a value from the callback:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  const pathname = useEvent("location", ({ to }) => to.pathname);
+  return <div>Current path: {pathname}</div>;
+}
+```
+
+### 3. Using a Callback for Side Effects
+
+If you just want to perform side effects when the event occurs:
+
+```typescript
+import { useEvent } from "@lukoweb/apitogo/hooks";
+
+function MyComponent() {
+  useEvent("location", ({ from, to }) => {
+    if (from) {
+      console.log(`Navigation: ${from.pathname} → ${to.pathname}`);
+    }
+    // No return value needed for side effects
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+The `useEvent` hook automatically handles subscription and cleanup in the React lifecycle, making it
+easy to work with events in your components.

package/docs/guides/custom-pages.md

@@ -0,0 +1,106 @@
+---
+title: Custom pages
+sidebar_icon: layers-3
+---
+
+If you want to include pages in your documentation that have greater flexibility than MDX pages, it
+is possible to include custom pages of your own.
+
+These pages are typically built using standard React markup and can borrow from a set of prebuilt
+components that APIToGo already has such as buttons, links and headers.
+
+Start by creating the page you want to add.
+
+## Setup a custom page
+
+Each custom page is a page component of its own and lives in a `src` directory at the root of your
+project. Let's create the `<MyCustomPage />` component as an example.
+
+From the root of your project run this command:
+
+```bash
+touch src/MyCustomPage.tsx
+```
+
+You can now open `/src/MyCustomPage.tsx` in the editor of your choice. It will be empty.
+
+Copy and paste this code to implement the page:
+
+```tsx
+import { Button, Head, Link } from "@lukoweb/apitogo/components";
+
+export const MyCustomPage = () => {
+  return (
+    <section className="">
+      <Head>
+        <title>My Custom Page</title>
+      </Head>
+      <div>
+        <p>Welcome to MyCustomPage</p>
+      </div>
+    </section>
+  );
+};
+```
+
+## Configuration
+
+In the [APIToGo Configuration](../configuration/overview.md) you will need to do the following:
+
+### Change Your Config Extension
+
+In order to embed `jsx`/`tsx` components into your APIToGo config, you will need to change your file
+extension from `ts` to `tsx` (or `js` to `jsx` if not using TypeScript).
+
+```
+apitogo.config.ts -> apitogo.config.tsx
+```
+
+### Import Your Module
+
+Import the `<MyCustomPage />` component that you created.
+
+```typescript
+import { MyCustomPage } from "./src/MyCustomPage";
+```
+
+### Add a navigation entry
+
+Add a `custom-page` item to the `navigation` configuration. Each page you want to add to the site
+must be its own object.
+
+The `path` key can be set to whatever you like. This will appear as part of the URL in the address
+bar of the browser.
+
+The `element` key references the name of the custom page component that you want to load.
+
+```typescript
+{
+  // ...
+  navigation: [
+    {
+      type: "custom-page",
+      path: "/a-custom-page",
+      element: <MyCustomPage />,
+    },
+  ]
+  // ...
+}
+```
+
+This configuration will allow APIToGo to load the contents of the `<MyCustomPage />` component when
+a user clicks on a link that points to `/a-custom-page`.
+
+## Troubleshooting
+
+### Updating Your `tsconfig.json`
+
+Your `include` property in `tsconfig.json` should automatically be updated to reflect the new custom
+pages, but in case it isn't, it should look like this:
+
+```json
+{
+  ...
+  "include": ["src", "apitogo.config.tsx", "src/MyCustomPage.tsx"]
+}
+```

package/docs/guides/environment-variables.md

@@ -0,0 +1,99 @@
+---
+title: Environment Variables
+sidebar_icon: table
+---
+
+APIToGo is built on top of Vite and uses [their approach](https://vite.dev/guide/env-and-mode) for
+managing environment variables.
+
+APIToGo exposes environment variables under the `import.meta.env` object as strings automatically.
+
+To prevent accidentally leaking environment variables to the client, only variables prefixed with
+`APITOGO_PUBLIC_` are exposed to your APIToGo-processed code.
+
+:::warning{title="Security Notice"}
+
+Environment variables prefixed with `APITOGO_PUBLIC_` will be exposed to the client-side code and
+visible in the browser. Never use this prefix for sensitive information like API keys, passwords, or
+other secrets.
+
+:::
+
+## Local Env Files
+
+When developing locally, you can create a `.env` file in the root of your project and add
+environment-specific variables. See the
+[Vite documentation](https://vite.dev/guide/env-and-mode.html#env-files) for more information on
+supported files.
+
+Here is an example of a `.env.local` file:
+
+```sh
+APITOGO_PUBLIC_PAGE_TITLE=My Page Title
+```
+
+You can access this variable in your application like this:
+
+```ts
+const title = import.meta.env.APITOGO_PUBLIC_PAGE_TITLE;
+```
+
+## Configuration Files
+
+Environment variables can also be used in your configuration files. When referencing environment
+variables in your configuration files, you can use `process.env` directly.
+
+```ts
+import type { ApitogoConfig } from "@lukoweb/apitogo";
+
+const config: ApitogoConfig = {
+  authentication: {
+    type: "auth0",
+    clientId: process.env.APITOGO_PUBLIC_AUTH_CLIENT_ID,
+    domain: process.env.APITOGO_PUBLIC_AUTH_DOMAIN,
+  },
+};
+```
+
+## React Components
+
+If you need to access environment variables inside a custom react component, you can access them via
+`import.meta.env`. Public environment variables are inlined during the build process.
+
+```tsx
+import React from "react";
+
+export const MyComponent = () => {
+  return <h1>{import.meta.env.APITOGO_PUBLIC_PAGE_TITLE}</h1>;
+};
+```
+
+## IntelliSense for TypeScript
+
+By default, APIToGo provides type definitions for `import.meta.env` in `apitogo/client.d.ts`. While
+you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript
+IntelliSense for user-defined env variables that are prefixed with `APITOGO_PUBLIC_`.
+
+To achieve this, you can create an `apitogo-env.d.ts` file in the src directory, then augment
+`ImportMetaEnv` like this:
+
+```typescript
+/// <reference types="@lukoweb/apitogo/client" />
+
+interface ImportMetaEnv {
+  readonly APITOGO_PUBLIC_APP_TITLE: string;
+  // more env variables...
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+:::warning{title="Imports will break type augmentation"}
+
+If the `ImportMetaEnv` augmentation does not work, make sure you do not have any import statements
+in `vite-env.d.ts`. A helpful explanation can be found on
+[this StackOverflow reply](https://stackoverflow.com/a/51114250).
+
+:::

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

@@ -0,0 +1,172 @@
+---
+title: Managing API Keys and Identities
+sidebar_label: API Keys and Identities
+sidebar_icon: key-square
+zuplo: false
+---
+
+## Managing API Keys in UI
+
+APIToGo comes with a Plugin to manage API keys in the UI. This plugin is build around the concept of
+API consumers, where each consumer can have multiple API keys. It includes functionality for
+creating, viewing, updating, and deleting API keys, as well as managing consumer information.
+
+:::note
+
+The most convenient way to use this plugin is to use it in Zuplo. However the plugin can be used
+with any other API key management system - you can use a 3rd party API key management system or
+build your own and still use the APIToGo UI.
+
+:::
+
+## Using in Zuplo
+
+To get started with a basic setup, simply enable `apiKeys` in your config. (In the default template,
+this is already enabled.)
+
+```typescript title=apitogo.config.ts
+{
+  // ...
+  apiKeys: {
+    enabled: true,
+  }
+}
+```
+
+This will make the API Key UI available at `/settings/api-keys` in your APIToGo.
+
+### Creating API Keys
+
+By default, there is no **Create API Key** Button. To get the button working you have to implement
+the `createKey` callback in your config. This callback is called when the user clicks the **Create
+API Key** button. The callback is passed the `apiKey` object that the user has entered, the
+`context` object, and the `auth` object. The `apiKey` object is the object that the user has entered
+in the Create API Key form.
+
+In this callback you can implement the logic to create a new API key. You can use the `auth` object
+to access the current users auth state. Most likley you want to call your API to create a new API
+key.
+
+```typescript title=apitogo.config.ts
+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,
+        }),
+      });
+
+      // Sign the request using current users Authentication
+      const signedRequest = await context.signRequest(createApiKeyRequest);
+
+      const response = await fetch(signedRequest);
+
+      if (!response.ok) {
+        throw new Error("Could not create API Key");
+      }
+
+      return true;
+    },
+  },
+};
+```
+
+## Using with any API Key Management System
+
+If you are not using Zuplo's API key management system, you can implement the `ApiKeyService`
+interface to connect to any API key management system.
+
+```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>;
+}
+
+interface ApiConsumer {
+  id: string;
+  label: string;
+  keys: ApiKey[];
+}
+
+interface ApiKey {
+  id: string;
+  key: string;
+  description?: string;
+  createdOn: string;
+  expiresOn?: string;
+}
+```
+
+### Implementing API Key Management
+
+Here's a step-by-step guide to implementing API key management:
+
+1. First, create a service that implements the `ApiKeyService` interface:
+
+```typescript title=apitogo.config.ts
+const config = {
+  // ...
+  apiKeys: {
+    enabled: true,
+
+    // Retrieve all API consumers and their keys
+    getConsumers: async (context) => {
+      // Implement fetching consumers from your storage
+      // Each consumer can have multiple API keys
+      return consumers;
+    },
+
+    // Create a new API key for a consumer
+    createKey: async ({ apiKey, context, auth }) => {
+      const newKey: ApiKey = {
+        id: crypto.randomUUID(),
+        key: `key-${crypto.randomUUID()}`,
+        description: apiKey.description,
+        createdOn: new Date().toISOString(),
+        expiresOn: apiKey.expiresOn,
+      };
+      // Save the new key to your storage
+      // Associate it with the current user/consumer
+    },
+
+    // Delete an API key
+    deleteKey: async (consumerId, keyId, context) => {
+      // Remove the key from the consumer's keys in your storage
+    },
+
+    // Regenerate an API key
+    rollKey: async (consumerId, context) => {
+      // Update the key value for the consumer while maintaining metadata
+    },
+
+    // Update consumer information
+    updateConsumer: async (consumer, context) => {
+      // Update the consumer's label or other metadata
+    },
+
+    // Get API usage statistics (optional)
+    getUsage: async (apiKeys, context) => {
+      // Fetch usage data for the provided API keys
+    },
+  },
+};
+```