@prauga/flexdoc-backend 2.1.0

package/README.md

@@ -0,0 +1,227 @@
+# FlexDoc Backend
+
+[![npm version](https://img.shields.io/npm/v/@prauga/flexdoc-backend.svg)](https://www.npmjs.com/package/@prauga/flexdoc-backend)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The backend package for FlexDoc, a modern, customizable OpenAPI documentation generator that creates beautiful API documentation.
+
+## Screenshots
+
+### Light Mode
+
+![FlexDoc Light Mode](./images/flexdoc-light.png)
+
+### Dark Mode
+
+![FlexDoc Dark Mode](./images/flexdoc-dark.png)
+
+## Features
+
+- **Modern UI**: Clean, responsive interface with dark mode support
+- **Customizable**: Easily customize colors, typography, and layout
+- **Interactive**: Test API endpoints directly from the documentation
+- **Framework Agnostic**: Works with any JavaScript framework
+- **OpenAPI Compatible**: Supports OpenAPI 3.0 specifications
+
+## Installation
+
+```bash
+npm install @prauga/flexdoc-backend
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { FlexDoc } from '@prauga/flexdoc-backend';
+import { OpenAPIObject } from '@nestjs/swagger';
+
+// Create a new FlexDoc instance with your OpenAPI spec
+const flexdoc = new FlexDoc({
+  spec: yourOpenAPISpec as OpenAPIObject,
+  title: 'My API Documentation',
+  description: 'Documentation for my awesome API',
+});
+
+// Generate HTML documentation
+const html = flexdoc.generateHTML();
+
+// Serve the documentation
+app.get('/api/docs', (req, res) => {
+  res.send(html);
+});
+```
+
+### Configuration Options
+
+FlexDoc is highly customizable through the `FlexDocOptions` interface:
+
+```typescript
+import { FlexDoc, FlexDocOptions } from '@prauga/flexdoc-backend';
+
+const options: FlexDocOptions = {
+  // Required
+  spec: yourOpenAPISpec,
+
+  // Basic metadata
+  title: 'My API Documentation',
+  description: 'Documentation for my awesome API',
+
+  // Theme configuration
+  themeConfig: {
+    colors: {
+      primary: {
+        main: '#3b82f6',
+        light: '#eff6ff',
+        dark: '#2563eb',
+      },
+      // Additional color options...
+    },
+    typography: {
+      fontFamily: 'Inter, system-ui, sans-serif',
+      fontSize: '16px',
+      // Additional typography options...
+    },
+  },
+
+  // Footer customization
+  footer: {
+    copyright: '© 2025 My Company',
+    links: [
+      {
+        text: 'Terms',
+        url: '/terms',
+        icon: 'file-text', // Optional Lucide icon name
+      },
+      {
+        text: 'Privacy',
+        url: '/privacy',
+      },
+    ],
+  },
+
+  // Additional options...
+};
+
+const flexdoc = new FlexDoc(options);
+```
+
+### Framework Integration Examples
+
+#### NestJS
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { FlexDoc } from '@prauga/flexdoc-backend';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Create OpenAPI spec with Swagger
+  const config = new DocumentBuilder()
+    .setTitle('My API')
+    .setDescription('My API description')
+    .setVersion('1.0')
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+
+  // Create FlexDoc instance
+  const flexdoc = new FlexDoc({
+    spec: document,
+    title: 'My API Documentation',
+    description: 'Documentation for my awesome API',
+    footer: {
+      copyright: '© 2025 My Company',
+    },
+  });
+
+  // Serve FlexDoc at /api/docs
+  app.use('/api/docs', (req, res) => {
+    res.send(flexdoc.generateHTML());
+  });
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+#### Express
+
+```typescript
+import express from 'express';
+import { FlexDoc } from '@prauga/flexdoc-backend';
+import swaggerJsdoc from 'swagger-jsdoc';
+
+const app = express();
+
+// Generate OpenAPI spec
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'My API',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./src/routes/*.js'],
+};
+const openapiSpec = swaggerJsdoc(options);
+
+// Create FlexDoc instance
+const flexdoc = new FlexDoc({
+  spec: openapiSpec,
+  title: 'My API Documentation',
+});
+
+// Serve FlexDoc
+app.get('/api/docs', (req, res) => {
+  res.send(flexdoc.generateHTML());
+});
+
+app.listen(3000);
+```
+
+## API Reference
+
+### `FlexDoc` Class
+
+The main class for generating API documentation.
+
+#### Constructor
+
+```typescript
+constructor(options: FlexDocOptions)
+```
+
+#### Methods
+
+- `generateHTML()`: Generates the HTML documentation
+- `getOpenAPISpec()`: Returns the processed OpenAPI specification
+
+### `FlexDocOptions` Interface
+
+Configuration options for FlexDoc:
+
+| Property       | Type                            | Description                      |
+| -------------- | ------------------------------- | -------------------------------- |
+| `spec`         | `OpenAPIObject`                 | The OpenAPI specification object |
+| `title`        | `string`                        | Documentation title              |
+| `description`  | `string`                        | Documentation description        |
+| `themeConfig`  | `ThemeConfig`                   | Theme configuration              |
+| `footer`       | `FooterConfig`                  | Footer configuration             |
+| `favicon`      | `string`                        | URL to favicon                   |
+| `customCss`    | `string`                        | Custom CSS to inject             |
+| `customJs`     | `string`                        | Custom JavaScript to inject      |
+| `defaultTheme` | `'light' \| 'dark' \| 'system'` | Default theme mode               |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

package/dist/flexdoc.module.d.ts

@@ -0,0 +1,14 @@
+import { DynamicModule, OnModuleInit } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+import { FlexDocModuleOptions } from './interfaces';
+export declare class FlexDocModule implements OnModuleInit {
+    private readonly options;
+    private readonly httpAdapterHost?;
+    constructor(options: FlexDocModuleOptions, httpAdapterHost?: HttpAdapterHost | undefined);
+    onModuleInit(): void;
+    static forRoot(options: FlexDocModuleOptions): DynamicModule;
+    static forRootAsync(options: {
+        useFactory: (...args: any[]) => Promise<FlexDocModuleOptions> | FlexDocModuleOptions;
+        inject?: any[];
+    }): DynamicModule;
+}

package/dist/flexdoc.module.js

@@ -0,0 +1,77 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var FlexDocModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlexDocModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const setup_1 = require("./setup");
+const flexdoc_service_1 = require("./flexdoc.service");
+let FlexDocModule = FlexDocModule_1 = class FlexDocModule {
+    constructor(options, httpAdapterHost) {
+        this.options = options;
+        this.httpAdapterHost = httpAdapterHost;
+    }
+    onModuleInit() {
+        if (!this.httpAdapterHost) {
+            console.warn('HttpAdapterHost not available. FlexDoc routes will not be registered.');
+            return;
+        }
+        const httpAdapter = this.httpAdapterHost.httpAdapter;
+        if (!httpAdapter) {
+            console.warn('HTTP Adapter not available. FlexDoc routes will not be registered.');
+            return;
+        }
+        const app = httpAdapter.getInstance();
+        (0, setup_1.setupFlexDoc)(app, this.options.path, {
+            spec: this.options.spec,
+            specUrl: this.options.specUrl,
+            options: this.options.options,
+        });
+    }
+    static forRoot(options) {
+        return {
+            module: FlexDocModule_1,
+            providers: [
+                flexdoc_service_1.FlexDocService,
+                {
+                    provide: 'FLEXDOC_OPTIONS',
+                    useValue: options,
+                },
+            ],
+            exports: [flexdoc_service_1.FlexDocService],
+        };
+    }
+    static forRootAsync(options) {
+        return {
+            module: FlexDocModule_1,
+            providers: [
+                flexdoc_service_1.FlexDocService,
+                {
+                    provide: 'FLEXDOC_OPTIONS',
+                    useFactory: options.useFactory,
+                    inject: options.inject || [],
+                },
+            ],
+            exports: [flexdoc_service_1.FlexDocService],
+        };
+    }
+};
+exports.FlexDocModule = FlexDocModule;
+exports.FlexDocModule = FlexDocModule = FlexDocModule_1 = __decorate([
+    (0, common_1.Module)({}),
+    __param(0, (0, common_1.Inject)('FLEXDOC_OPTIONS')),
+    __metadata("design:paramtypes", [Object, core_1.HttpAdapterHost])
+], FlexDocModule);
+//# sourceMappingURL=flexdoc.module.js.map

package/dist/flexdoc.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flexdoc.module.js","sourceRoot":"","sources":["../src/flexdoc.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAMwB;AACxB,uCAA+C;AAC/C,mCAAuC;AACvC,uDAAmD;AAI5C,IAAM,aAAa,qBAAnB,MAAM,aAAa;IACxB,YAC8C,OAA6B,EACxD,eAAiC;QADN,YAAO,GAAP,OAAO,CAAsB;QACxD,oBAAe,GAAf,eAAe,CAAkB;IACjD,CAAC;IAEJ,YAAY;QACV,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CACV,uEAAuE,CACxE,CAAC;YACF,OAAO;QACT,CAAC;QAGD,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC;QACrD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CACV,oEAAoE,CACrE,CAAC;YACF,OAAO;QACT,CAAC;QAGD,MAAM,GAAG,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAGtC,IAAA,oBAAY,EAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;YACnC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YACvB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,OAA6B;QAC1C,OAAO;YACL,MAAM,EAAE,eAAa;YACrB,SAAS,EAAE;gBACT,gCAAc;gBACd;oBACE,OAAO,EAAE,iBAAiB;oBAC1B,QAAQ,EAAE,OAAO;iBAClB;aACF;YACD,OAAO,EAAE,CAAC,gCAAc,CAAC;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAKnB;QACC,OAAO;YACL,MAAM,EAAE,eAAa;YACrB,SAAS,EAAE;gBACT,gCAAc;gBACd;oBACE,OAAO,EAAE,iBAAiB;oBAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;iBAC7B;aACF;YACD,OAAO,EAAE,CAAC,gCAAc,CAAC;SAC1B,CAAC;IACJ,CAAC;CACF,CAAA;AAnEY,sCAAa;wBAAb,aAAa;IADzB,IAAA,eAAM,EAAC,EAAE,CAAC;IAGN,WAAA,IAAA,eAAM,EAAC,iBAAiB,CAAC,CAAA;6CACS,sBAAe;GAHzC,aAAa,CAmEzB"}

package/dist/flexdoc.module.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flexdoc.module.test.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const flexdoc_module_1 = require("./flexdoc.module");
+const setup_1 = require("./setup");
+jest.mock('./setup', () => ({
+    setupFlexDoc: jest.fn(),
+}));
+describe('FlexDocModule', () => {
+    let app;
+    let mockHttpAdapterHost;
+    beforeEach(() => {
+        app = { use: jest.fn() };
+        mockHttpAdapterHost = {
+            httpAdapter: {
+                getInstance: jest.fn().mockReturnValue(app),
+            },
+        };
+        jest.clearAllMocks();
+    });
+    describe('forRoot', () => {
+        it('registers static options and installs FlexDoc on module init', () => {
+            const options = {
+                path: '/api-docs',
+                spec: { openapi: '3.0.0' },
+            };
+            const dynamicModule = flexdoc_module_1.FlexDocModule.forRoot(options);
+            const optionsProvider = dynamicModule.providers.find((provider) => provider.provide === 'FLEXDOC_OPTIONS');
+            expect(optionsProvider.useValue).toBe(options);
+            const module = new flexdoc_module_1.FlexDocModule(options, mockHttpAdapterHost);
+            module.onModuleInit();
+            expect(setup_1.setupFlexDoc).toHaveBeenCalledWith(app, '/api-docs', expect.objectContaining({ spec: { openapi: '3.0.0' } }));
+        });
+    });
+    describe('forRootAsync', () => {
+        it('registers an async options factory and installs its result', async () => {
+            const options = {
+                path: '/api-docs',
+                spec: { openapi: '3.0.0' },
+            };
+            const useFactory = jest.fn().mockResolvedValue(options);
+            const dynamicModule = flexdoc_module_1.FlexDocModule.forRootAsync({ useFactory });
+            const optionsProvider = dynamicModule.providers.find((provider) => provider.provide === 'FLEXDOC_OPTIONS');
+            const resolvedOptions = await optionsProvider.useFactory();
+            expect(useFactory).toHaveBeenCalled();
+            const module = new flexdoc_module_1.FlexDocModule(resolvedOptions, mockHttpAdapterHost);
+            module.onModuleInit();
+            expect(setup_1.setupFlexDoc).toHaveBeenCalledWith(app, '/api-docs', expect.objectContaining({ spec: { openapi: '3.0.0' } }));
+        });
+        it('preserves dependency injection metadata for the options factory', async () => {
+            const mockServiceToken = 'MockService';
+            const mockService = {
+                getSpec: jest.fn().mockReturnValue({ openapi: '3.0.0' }),
+            };
+            const useFactory = (service) => ({
+                path: '/api-docs',
+                spec: service.getSpec(),
+            });
+            const dynamicModule = flexdoc_module_1.FlexDocModule.forRootAsync({
+                useFactory,
+                inject: [mockServiceToken],
+            });
+            const optionsProvider = dynamicModule.providers.find((provider) => provider.provide === 'FLEXDOC_OPTIONS');
+            expect(optionsProvider.inject).toEqual([mockServiceToken]);
+            const resolvedOptions = await optionsProvider.useFactory(mockService);
+            const module = new flexdoc_module_1.FlexDocModule(resolvedOptions, mockHttpAdapterHost);
+            module.onModuleInit();
+            expect(mockService.getSpec).toHaveBeenCalled();
+            expect(setup_1.setupFlexDoc).toHaveBeenCalledWith(app, '/api-docs', expect.objectContaining({ spec: { openapi: '3.0.0' } }));
+        });
+    });
+});
+//# sourceMappingURL=flexdoc.module.test.js.map

package/dist/flexdoc.module.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flexdoc.module.test.js","sourceRoot":"","sources":["../src/flexdoc.module.test.ts"],"names":[],"mappings":"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"}

package/dist/flexdoc.service.d.ts

@@ -0,0 +1,5 @@
+import { FlexDocOptions } from './interfaces';
+export declare class FlexDocService {
+    generateHTML(spec: object, options?: FlexDocOptions): string;
+    generateHTMLFromUrl(specUrl: string, options?: FlexDocOptions): string;
+}

package/dist/flexdoc.service.js

@@ -0,0 +1,24 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlexDocService = void 0;
+const common_1 = require("@nestjs/common");
+const template_1 = require("./template");
+let FlexDocService = class FlexDocService {
+    generateHTML(spec, options = {}) {
+        return (0, template_1.generateFlexDocHTML)(spec, options);
+    }
+    generateHTMLFromUrl(specUrl, options = {}) {
+        return (0, template_1.generateFlexDocHTML)(null, { ...options, specUrl });
+    }
+};
+exports.FlexDocService = FlexDocService;
+exports.FlexDocService = FlexDocService = __decorate([
+    (0, common_1.Injectable)()
+], FlexDocService);
+//# sourceMappingURL=flexdoc.service.js.map

package/dist/flexdoc.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flexdoc.service.js","sourceRoot":"","sources":["../src/flexdoc.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAE5C,yCAAiD;AAG1C,IAAM,cAAc,GAApB,MAAM,cAAc;IACzB,YAAY,CAAC,IAAY,EAAE,UAA0B,EAAE;QACrD,OAAO,IAAA,8BAAmB,EAAC,IAA+B,EAAE,OAAO,CAAC,CAAC;IACvE,CAAC;IAED,mBAAmB,CAAC,OAAe,EAAE,UAA0B,EAAE;QAC/D,OAAO,IAAA,8BAAmB,EAAC,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF,CAAA;AARY,wCAAc;yBAAd,cAAc;IAD1B,IAAA,mBAAU,GAAE;GACA,cAAc,CAQ1B"}

package/dist/framework-adapters.d.ts

@@ -0,0 +1,25 @@
+import { FlexDocModuleOptions } from './interfaces';
+export interface ExpressLikeApplication {
+    use(path: string, handler: (req: any, res: any, next?: any) => void | Promise<void>): void;
+}
+export interface FastifyLikeReply {
+    code(statusCode: number): FastifyLikeReply;
+    type(contentType: string): FastifyLikeReply;
+    header(name: string, value: string): FastifyLikeReply;
+    send(payload: any): any;
+}
+export interface FastifyLikeRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+export interface FastifyLikeApplication {
+    get(path: string, options: Record<string, unknown>, handler: (req: FastifyLikeRequest, reply: FastifyLikeReply) => any | Promise<any>): void;
+}
+export interface NestLikeApplication {
+    getHttpAdapter(): {
+        getType?: () => string;
+        getInstance: () => any;
+    };
+}
+export declare function setupExpressFlexDoc(app: ExpressLikeApplication, path: string, options: Omit<FlexDocModuleOptions, 'path'>): void;
+export declare function setupFastifyFlexDoc(app: FastifyLikeApplication, path: string, options: Omit<FlexDocModuleOptions, 'path'>): void;
+export declare function setupNestFlexDoc(app: NestLikeApplication, path: string, swaggerDocumentOptions: Record<string, unknown>, options?: Omit<FlexDocModuleOptions, 'path' | 'spec' | 'specUrl'>): void;

package/dist/framework-adapters.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupExpressFlexDoc = setupExpressFlexDoc;
+exports.setupFastifyFlexDoc = setupFastifyFlexDoc;
+exports.setupNestFlexDoc = setupNestFlexDoc;
+const crypto = __importStar(require("crypto"));
+const jwt = __importStar(require("jsonwebtoken"));
+const renderer_assets_1 = require("./renderer-assets");
+const setup_1 = require("./setup");
+const template_1 = require("./template");
+function setupExpressFlexDoc(app, path, options) {
+    (0, setup_1.setupFlexDoc)(app, path, options);
+}
+function generatedPassword(username, secret) {
+    const hash = crypto.createHmac('sha256', secret).update(username).digest('base64').substring(0, 12);
+    let password = hash;
+    if (!/[A-Z]/.test(password))
+        password += 'A';
+    if (!/[a-z]/.test(password))
+        password += 'a';
+    if (!/[0-9]/.test(password))
+        password += '1';
+    if (!/[^A-Za-z0-9]/.test(password))
+        password += '!';
+    return password;
+}
+function authorize(headers, auth) {
+    if (!auth)
+        return true;
+    const raw = headers.authorization;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (!value)
+        return false;
+    if (auth.type === 'basic') {
+        if (!value.startsWith('Basic '))
+            return false;
+        const decoded = Buffer.from(value.slice(6), 'base64').toString('utf8');
+        const separator = decoded.indexOf(':');
+        const username = separator < 0 ? decoded : decoded.slice(0, separator);
+        const password = separator < 0 ? '' : decoded.slice(separator + 1);
+        return password === generatedPassword(username, auth.secretKey);
+    }
+    let token;
+    if (value.startsWith('Bearer '))
+        token = value.slice(7);
+    else if (value.startsWith('Basic ')) {
+        const decoded = Buffer.from(value.slice(6), 'base64').toString('utf8');
+        const separator = decoded.indexOf(':');
+        if (separator >= 0)
+            token = decoded.slice(separator + 1);
+    }
+    if (!token)
+        return false;
+    try {
+        jwt.verify(token, auth.secretKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadRemoteSpec(url) {
+    const response = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(10000) });
+    if (!response.ok)
+        throw new Error(`Failed to load OpenAPI spec: HTTP ${response.status}`);
+    return response.json();
+}
+function setupFastifyFlexDoc(app, path, options) {
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    const rendererBasePath = `${normalizedPath}/__flexdoc`;
+    const auth = options.options?.auth;
+    let remoteSpecPromise = null;
+    const routeOptions = auth ? {
+        preHandler: async (request, reply) => {
+            if (!authorize(request.headers, auth)) {
+                reply.header('WWW-Authenticate', auth.type === 'basic' ? 'Basic' : 'Bearer');
+                return reply.code(401).send('Authentication required');
+            }
+        },
+    } : {};
+    const resolvedSpec = async () => {
+        if (options.spec)
+            return options.spec;
+        if (!options.specUrl)
+            return null;
+        if (!remoteSpecPromise)
+            remoteSpecPromise = loadRemoteSpec(options.specUrl).catch((error) => {
+                remoteSpecPromise = null;
+                throw error;
+            });
+        return remoteSpecPromise;
+    };
+    app.get(`${rendererBasePath}/renderer.js`, routeOptions, async (_request, reply) => {
+        const assets = (0, renderer_assets_1.getRendererAssets)();
+        return reply.type('application/javascript; charset=utf-8').header('Cache-Control', 'public, max-age=31536000, immutable').send(assets.javascript);
+    });
+    app.get(`${rendererBasePath}/renderer.css`, routeOptions, async (_request, reply) => {
+        const assets = (0, renderer_assets_1.getRendererAssets)();
+        return reply.type('text/css; charset=utf-8').header('Cache-Control', 'public, max-age=31536000, immutable').send(assets.css);
+    });
+    app.get(normalizedPath, routeOptions, async (_request, reply) => {
+        try {
+            const html = (0, template_1.generateFlexDocHTML)(await resolvedSpec(), { ...(options.options || {}), rendererBasePath });
+            return reply.type('text/html; charset=utf-8').send(html);
+        }
+        catch (error) {
+            return reply.code(502).type('text/plain; charset=utf-8').send(`Unable to load OpenAPI specification: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    });
+}
+function setupNestFlexDoc(app, path, swaggerDocumentOptions, options = {}) {
+    let SwaggerModule;
+    try {
+        SwaggerModule = require('@nestjs/swagger').SwaggerModule;
+    }
+    catch {
+        throw new Error('setupNestFlexDoc requires @nestjs/swagger to be installed');
+    }
+    const spec = SwaggerModule.createDocument(app, swaggerDocumentOptions);
+    const adapter = app.getHttpAdapter();
+    const instance = adapter.getInstance();
+    const type = adapter.getType?.();
+    if (type === 'fastify' || (!instance.use && typeof instance.get === 'function')) {
+        setupFastifyFlexDoc(instance, path, { ...options, spec });
+    }
+    else {
+        setupExpressFlexDoc(instance, path, { ...options, spec });
+    }
+}
+//# sourceMappingURL=framework-adapters.js.map

package/dist/framework-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-adapters.js","sourceRoot":"","sources":["../src/framework-adapters.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,kDAEC;AA0CD,kDA2CC;AAMD,4CAqBC;AAhJD,+CAAiC;AACjC,kDAAoC;AAEpC,uDAAsD;AACtD,mCAAuC;AACvC,yCAAiD;AAyBjD,SAAgB,mBAAmB,CAAC,GAA2B,EAAE,IAAY,EAAE,OAA2C;IACxH,IAAA,oBAAY,EAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpG,IAAI,QAAQ,GAAG,IAAI,CAAC;IACpB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,QAAQ,IAAI,GAAG,CAAC;IAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,QAAQ,IAAI,GAAG,CAAC;IAC7C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,QAAQ,IAAI,GAAG,CAAC;IAC7C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,QAAQ,IAAI,GAAG,CAAC;IACpD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,SAAS,CAAC,OAAsC,EAAE,IAAsD;IAC/G,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC;IAClC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACnE,OAAO,QAAQ,KAAK,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,KAAyB,CAAC;IAC9B,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACnD,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,SAAS,IAAI,CAAC;YAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AACjF,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,GAAW;IACvC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,KAAM,CAAC,EAAE,CAAC,CAAC;IAC/F,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1F,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED,SAAgB,mBAAmB,CAAC,GAA2B,EAAE,IAAY,EAAE,OAA2C;IACxH,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAChE,MAAM,gBAAgB,GAAG,GAAG,cAAc,YAAY,CAAC;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC;IACnC,IAAI,iBAAiB,GAAwB,IAAI,CAAC;IAElD,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;QAC1B,UAAU,EAAE,KAAK,EAAE,OAA2B,EAAE,KAAuB,EAAE,EAAE;YACzE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;gBACtC,KAAK,CAAC,MAAM,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAC7E,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;KACF,CAAC,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,YAAY,GAAG,KAAK,IAAI,EAAE;QAC9B,IAAI,OAAO,CAAC,IAAI;YAAE,OAAO,OAAO,CAAC,IAAI,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,CAAC,iBAAiB;YAAE,iBAAiB,GAAG,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC1F,iBAAiB,GAAG,IAAI,CAAC;gBACzB,MAAM,KAAK,CAAC;YACd,CAAC,CAAC,CAAC;QACH,OAAO,iBAAiB,CAAC;IAC3B,CAAC,CAAC;IAEF,GAAG,CAAC,GAAG,CAAC,GAAG,gBAAgB,cAAc,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QACjF,MAAM,MAAM,GAAG,IAAA,mCAAiB,GAAE,CAAC;QACnC,OAAO,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE,qCAAqC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACpJ,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,GAAG,gBAAgB,eAAe,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAClF,MAAM,MAAM,GAAG,IAAA,mCAAiB,GAAE,CAAC;QACnC,OAAO,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE,qCAAqC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/H,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QAC9D,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAA,8BAAmB,EAAC,MAAM,YAAY,EAAE,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;YACzG,OAAO,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC,IAAI,CAAC,yCAAyC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;QACrK,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAMD,SAAgB,gBAAgB,CAC9B,GAAwB,EACxB,IAAY,EACZ,sBAA+C,EAC/C,UAAmE,EAAE;IAErE,IAAI,aAAkB,CAAC;IACvB,IAAI,CAAC;QACH,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,aAAa,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,cAAc,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;IACjC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,IAAI,OAAO,QAAQ,CAAC,GAAG,KAAK,UAAU,CAAC,EAAE,CAAC;QAChF,mBAAmB,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;SAAM,CAAC;QACN,mBAAmB,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC"}

package/dist/framework-adapters.test.d.ts

@@ -0,0 +1 @@
+export {};