# @luckystack/docs-ui

Dev-only API docs UI for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2).

Mounts a single page at `/_docs` that fetches the framework's generated
`apiDocs.generated.json` and renders every API endpoint grouped by page,
with HTTP method, auth requirements, rate limit, input shape, and output
shape.

## Install

```bash
npm install @luckystack/docs-ui
```

Peer deps (already installed if you have any other LuckyStack package):

- `@luckystack/core`
- `@luckystack/server` (the docs UI is mounted via `createLuckyStackServer`'s `customRoutes` option)

## Quickstart

```ts
// luckystack/docs-ui/index.ts (overlay file — auto-imported by bootstrapLuckyStack)
import { mountDocsUi } from '@luckystack/docs-ui';

export const docsUiHandler = mountDocsUi({
  // Title shown in the header + browser tab. Defaults to 'LuckyStack — API docs'.
  // Pass your project name explicitly — there's no implicit lookup from
  // ProjectConfig because consumer config shapes vary too widely to introspect.
  pageTitle: 'My App — API docs',
});
```

```ts
// server/server.ts
import { docsUiHandler } from '../luckystack/docs-ui';
import { bootstrapLuckyStack } from '@luckystack/server';
import { serveFile, serveFavicon } from './prod/serveFile';

await (await bootstrapLuckyStack({
  serveFile,
  serveFavicon,
  customRoutes: docsUiHandler,
})).listen();
```

Open `http://localhost/_docs` and you'll see every API in your project,
grouped by page, with one-click expand for each endpoint's input/output.

## Production

By default the route returns 404 in production (`NODE_ENV === 'production'`).
Pass `{ enabledInProd: true }` to render it anyway — useful for an internal
developer-portal deployment, but **never** safe on a public surface unless
your APIs are intentionally documented to the world.

## Options

| Option | Default | Notes |
| --- | --- | --- |
| `routePath` | `/_docs` | Path the page is served from. The JSON is at `${routePath}/api.json`. |
| `pageTitle` | `LuckyStack — API docs` | Shown in the header + browser tab. Pass your project name explicitly — there is no implicit lookup from `ProjectConfig`. |
| `enabledInProd` | `false` | Set to `true` to render the docs in production. |
| `apiDocsPath` | `getGeneratedApiDocsPath()` | Override the JSON file path. Default reads from `ProjectConfig.paths.generatedApiDocs`. |
| `branding` | `{}` | `{ logoUrl?, brandColor?, fontFamily? }` applied by the default template (logo in the header, accent color, font). Ignored when a custom `template` is supplied. |
| `template` | `undefined` | `DocsTemplateBuilder` — a custom HTML builder `({ jsonPath, pageTitle, branding }) => string`. When set, the default `renderDocsHtml` is bypassed entirely. |
| `enableTryItOut` | `false` | Renders an inline request runner (textarea + Send) under each endpoint that calls the live server with `credentials: 'include'`. Needs a logged-in browser session. |
| `authorize` | `undefined` | `(req) => boolean \| Promise<boolean>` per-request hook, run after the env/bind-address gate. Return `false` to serve `403`. Use to restrict docs access on non-loopback deployments. |

## How it works

The docs page is a single embedded HTML file (no build step, no React, no
external dependencies). It fetches `${routePath}/api.json` at runtime,
which is served from the project's `apiDocs.generated.json` — generated by
`@luckystack/devkit`'s type-map emitter on every dev-server reload and on
every `npm run generateArtifacts`.

The handler is a `customRoutes` predicate: it returns `true` when it
matches the configured paths, `false` otherwise — so it composes cleanly
with any other custom HTTP handler.

## Related architecture docs

- [`docs/ARCHITECTURE_API.md`](../../docs/ARCHITECTURE_API.md) — the lifecycle these endpoints document.
- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — how `apiDocs.generated.json` is produced.

## License

MIT — see the [repository LICENSE](https://github.com/ItsLucky23/LuckyStack-v2/blob/master/LICENSE).