# Elysia LLMs TXT

An Elysia plugin that generates `llms.txt` documentation from OpenAPI/Swagger specifications. Transform your API specs into LLM-friendly documentation with automatic endpoint generation.

[![npm version](https://badge.fury.io/js/%40opuu%2Felysia-llms-txt.svg)](https://badge.fury.io/js/%40opuu%2Felysia-llms-txt)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Elysia](https://img.shields.io/badge/Elysia-Plugin-green.svg)](https://elysiajs.com/)

## Why Elysia LLMs TXT?

Elysia LLMs TXT bridges the gap between your API documentation and AI consumption, making it perfect for:

- **LLM Integration**: Generate AI-friendly documentation that large language models can easily parse
- **API Documentation**: Convert OpenAPI/Swagger specs into readable markdown format
- **Developer Experience**: Provide `/llms.txt` endpoints for instant API documentation access
- **AI Training**: Create structured documentation suitable for training AI models on your API
- **Documentation Automation**: Automatically generate and serve API documentation without manual maintenance

## Key Features

- **OpenAPI/Swagger Support**: Works with both file-based and URL-based OpenAPI specifications
- **JSON & YAML Support**: Automatically detects and parses both JSON and YAML formats
- **LLM-Optimized Output**: Generates markdown documentation specifically formatted for AI consumption
- **Elysia Native**: Built specifically for Elysia with TypeScript support
- **Flexible Configuration**: Customizable headers, footers, and content types
- **Standard Endpoints**: Provides `/llms.txt` and `/llms-full.txt` endpoints automatically
- **Built-in Caching**: Optional LRU cache with configurable TTL and max size

## Installation

```bash
npm install @opuu/elysia-llms-txt
```

```bash
pnpm add @opuu/elysia-llms-txt
```

```bash
yarn add @opuu/elysia-llms-txt
```

```bash
bun add @opuu/elysia-llms-txt
```

## Quick Start

### 1. Basic Usage

```typescript
import { Elysia } from "elysia";
import { llms } from "@opuu/elysia-llms-txt";

const app = new Elysia()
  .use(
    llms({
      source: {
        type: "url",
        url: "/swagger/json",
      },
    })
  )
  .listen(3000);

// Visit: http://localhost:3000/llms.txt
```

### 2. File-based Configuration

```typescript
import { Elysia } from "elysia";
import { llms } from "@opuu/elysia-llms-txt";

const app = new Elysia()
  .use(
    llms({
      source: {
        type: "file",
        file: "./openapi.json",
      },
      header: "# My API Documentation",
      footer: "Generated for LLM consumption",
    })
  )
  .listen(3000);
```

### 3. Advanced Configuration

```typescript
import { Elysia } from "elysia";
import { llms } from "@opuu/elysia-llms-txt";

const app = new Elysia()
  .use(
    llms({
      source: {
        type: "url",
        url: "https://petstore.swagger.io/v2/swagger.json",
      },
      header: `# Petstore API Documentation
    
This documentation is optimized for Large Language Models.`,
      footer: `
---
Last updated: ${new Date().toISOString()}
Generated by @opuu/elysia-llms-txt`,
      contentType: "text/markdown",
    })
  )
  .listen(3000);
```

## API Reference

### Configuration Options

The plugin accepts an `LLMsOptions` object with the following properties:

| Option        | Type                              | Description                           | Default           |
| ------------- | --------------------------------- | ------------------------------------- | ----------------- |
| `source`      | `object`                          | Source configuration for OpenAPI spec | Required          |
| `source.type` | `"file" \| "url"`                 | Whether to load from file or URL      | Required          |
| `source.file` | `string`                          | File path (when type is "file")       | Optional          |
| `source.url`  | `string`                          | URL path (when type is "url")         | Optional          |
| `header`      | `string`                          | Optional header content               | Optional          |
| `footer`      | `string`                          | Optional footer content               | Optional          |
| `contentType` | `"text/markdown" \| "text/plain"` | Response content type                 | `"text/markdown"` |
| `cache`       | `object`                          | Cache configuration                   | Optional          |
| `cache.enabled` | `boolean`                       | Enable response caching               | `false`           |
| `cache.ttl`   | `number`                          | Cache TTL in milliseconds             | `60000`           |
| `cache.maxSize` | `number`                        | Max cache entries (LRU eviction)      | `100`             |

### YAML Support

The plugin automatically detects and parses YAML OpenAPI specs. To enable YAML support, install `js-yaml`:

```bash
npm install js-yaml
```

YAML files are detected by:
1. File extension (`.yaml` or `.yml`)
2. Content analysis (if not starting with `{` or `[`)

### Generated Endpoints

The plugin automatically adds these endpoints to your Elysia application:

- `GET /llms.txt` - Returns the generated LLM documentation
- `GET /llms-full.txt` - Redirects to `/llms.txt` (for compatibility)

## Requirements

- Node.js >= 18.0.0
- Bun >= 1.0.0
- Elysia >= 1.0.0

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.