@flink-app/api-docs-plugin 0.12.1-alpha.4 → 0.12.1-alpha.40

package/BUILD.md

@@ -0,0 +1,52 @@
+# Build Process for API Docs Plugin
+
+This plugin consists of two main parts:
+1. The TypeScript plugin code
+2. A React application for the documentation UI
+
+## Directory Structure
+
+```
+api-docs-plugin/
+├── src/                    # TypeScript plugin source
+├── react-app/              # React application source
+│   ├── src/                # React components
+│   └── dist/               # Built React files (after build)
+└── dist/                   # Compiled plugin output
+    ├── index.js            # Compiled plugin
+    └── react-app/          # Copied React build files
+```
+
+## Build Process
+
+The build process follows these steps:
+
+1. **Build React App**: 
+   - Runs `npm run build` in the `react-app` directory
+   - Outputs files to `react-app/dist`
+
+2. **Compile TypeScript**:
+   - Compiles all TypeScript files from `src/` to `dist/`
+
+3. **Copy Assets**:
+   - Copies the built React app from `react-app/dist` to `dist/react-app`
+
+## Commands
+
+- `npm run prepare`: Runs the full build process (React + TypeScript + copy)
+- `npm run build:react`: Builds only the React app
+- `npm run clean`: Removes the dist directory
+
+## How It Works
+
+1. The plugin serves the React app from `dist/react-app` at the `/docs` endpoint
+2. The React app fetches API data from `/docs/api`
+3. The plugin provides the API data based on registered Flink handlers
+
+## Development
+
+For development, you can run:
+- `npm run dev`: Starts a development server
+- `npm run watch`: Watches for TypeScript changes
+
+Make sure to build the React app before testing the full plugin.

package/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development Guide for API Docs Plugin
+
+This guide explains how to develop the API Docs Plugin React app.
+
+## Prerequisites
+
+- Node.js installed (see root .nvmrc for version)
+- Dependencies installed in both the plugin root and react-app directories:
+  ```bash
+  npm install
+  cd react-app && npm install
+  ```
+
+## Development Setup
+
+The development setup consists of two servers:
+
+1. **Mock API Server** (port 3001): Serves sample API data
+2. **Vite Dev Server** (port 5173): Serves the React app with hot-reloading
+
+## Running the Development Environment
+
+1. Start the mock API server:
+   ```bash
+   npm run dev:mock-api
+   ```
+
+2. In another terminal, start the React dev server:
+   ```bash
+   npm run dev:react
+   ```
+
+3. Open http://localhost:5173 in your browser
+
+The React app will fetch data from the mock API server through Vite's proxy configuration.
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev:mock-api` | Start the mock API server |
+| `npm run dev:react` | Start the React development server |
+| `npm run build:react` | Build the React app for production |
+| `npm run prepare` | Build everything for production |
+| `npm run clean` | Remove all build artifacts |
+
+## Modifying Sample Data
+
+To test different API structures, edit `sample.json` and restart the mock API server.
+
+## Building for Production
+
+To build the complete plugin:
+
+```bash
+npm run prepare
+```
+
+This will:
+1. Build the React app
+2. Compile TypeScript
+3. Copy assets to the dist directory
+
+The built plugin will serve the React app statically in production.

package/dist/dev-server.d.ts

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

package/dist/dev-server.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var express_1 = __importDefault(require("express"));
+var path_1 = __importDefault(require("path"));
+var fs_1 = __importDefault(require("fs"));
+var app = (0, express_1.default)();
+var port = 3001;
+// Configure development options
+var options = {
+    apiPath: "/docs/api"
+};
+// Load sample data
+var sampleData;
+try {
+    sampleData = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, "../sample.json"), "utf-8"));
+    console.log("Sample data loaded successfully");
+}
+catch (error) {
+    console.error("Failed to load sample.json:", error);
+    process.exit(1);
+}
+// Enable CORS for development
+app.use(function (req, res, next) {
+    res.header("Access-Control-Allow-Origin", "*");
+    res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
+    next();
+});
+// Serve API endpoint
+app.get(options.apiPath, function (req, res) {
+    console.log("API request received at ".concat(options.apiPath));
+    res.json({
+        routes: Array.isArray(sampleData) ? sampleData : [sampleData]
+    });
+});
+// Start the server
+app.listen(port, function () {
+    console.log("Mock API server running at http://localhost:".concat(port));
+    console.log("API endpoint available at http://localhost:".concat(port).concat(options.apiPath));
+    console.log("\nTo develop the React app:");
+    console.log("1. Keep this server running");
+    console.log("2. In another terminal, cd to react-app and run 'npm run dev'");
+    console.log("3. Open http://localhost:5173 to see the app");
+});

package/dist/index.d.ts

@@ -2,8 +2,14 @@ import { FlinkPlugin } from "@flink-app/flink";
 export type ApiDocOptions = {
     /**
      * Path to where api docs can be accessed
+     * Defaults to "/docs"
      */
     path?: string;
+    /**
+     * Path to where route and schemas are fetched from.
+     * Defaults to "/docs/api"
+     */
+    apiPath?: string;
     /**
      * Name of plugin
      */

package/dist/index.js

@@ -1,7 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.apiDocPlugin = void 0;
-var path_1 = require("path");
+var path_1 = __importDefault(require("path"));
+var express_1 = __importDefault(require("express"));
 var apiDocPlugin = function (options) {
     if (options === void 0) { options = {}; }
     return {
@@ -11,23 +15,15 @@ var apiDocPlugin = function (options) {
 };
 exports.apiDocPlugin = apiDocPlugin;
 function init(app, options) {
-    // TODO: Use parsedHandlerConfig
     var expressApp = app.expressApp, handlers = app.handlers;
     if (!expressApp) {
         // should not happen
         throw new Error("Express app not initialized");
     }
-    // NOTE: This will probably break if any other plugin "claims" pug as view engine
-    expressApp.engine("pug", require("pug").__express);
-    expressApp.set("views", (0, path_1.join)(__dirname, "views"));
-    expressApp.set("view engine", "pug");
-    expressApp === null || expressApp === void 0 ? void 0 : expressApp.get(options.path || "/docs", function (req, res) {
-        var sortedHandlers = handlers.sort(function (routeA, routeB) {
-            return routeA.routeProps.path.localeCompare(routeB.routeProps.path);
-        });
-        res.render("index", {
-            title: options.title || "API Docs",
-            handlers: sortedHandlers,
-        });
+    var staticPath = path_1.default.resolve(__dirname, "react-app");
+    expressApp === null || expressApp === void 0 ? void 0 : expressApp.use(options.path || "/docs", express_1.default.static(staticPath));
+    expressApp === null || expressApp === void 0 ? void 0 : expressApp.get(options.apiPath || "/docs/api", function (req, res) {
+        var sortedHandlers = handlers.sort(function (routeA, routeB) { return routeA.routeProps.path.localeCompare(routeB.routeProps.path); });
+        res.json({ routes: sortedHandlers });
     });
 }

package/dist/mcp-server.d.ts

@@ -0,0 +1,3 @@
+import { FlinkApp } from "@flink-app/flink";
+import type { Request, Response } from "express";
+export declare function createMcpHandler(app: FlinkApp<any>): (req: Request, res: Response) => Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,250 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpHandler = void 0;
+// Helper function to simplify schema conversion
+function flattenProperties(properties, required, parent) {
+    if (required === void 0) { required = []; }
+    if (parent === void 0) { parent = ""; }
+    var result = [];
+    for (var _i = 0, _a = Object.entries(properties || {}); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], value = _b[1];
+        var path = parent ? "".concat(parent, ".").concat(key) : key;
+        result.push({
+            name: path,
+            type: value.type,
+            description: value.description,
+            required: required.includes(key),
+        });
+        if (value.type === "object" && value.properties) {
+            result = result.concat(flattenProperties(value.properties, value.required || [], path));
+        }
+        if (value.type === "array" && value.items && value.items.type === "object" && value.items.properties) {
+            result = result.concat(flattenProperties(value.items.properties, value.items.required || [], "".concat(path, "[]")));
+        }
+    }
+    return result;
+}
+// For creating an Express endpoint that handles MCP requests
+function createMcpHandler(app) {
+    var _this = this;
+    return function (req, res) { return __awaiter(_this, void 0, void 0, function () {
+        var endpoints, _a, method, params, tools, _b, name_1, args, endpoint, response_1;
+        return __generator(this, function (_c) {
+            try {
+                endpoints = app.handlers.map(function (handler) {
+                    var _a, _b, _c, _d, _e, _f;
+                    return ({
+                        path: handler.routeProps.path,
+                        method: handler.routeProps.method.toUpperCase(),
+                        description: (_b = (_a = handler.schema) === null || _a === void 0 ? void 0 : _a.reqSchema) === null || _b === void 0 ? void 0 : _b.description,
+                        queryParams: handler.queryMetadata,
+                        pathParams: handler.paramsMetadata,
+                        requestBody: ((_d = (_c = handler.schema) === null || _c === void 0 ? void 0 : _c.reqSchema) === null || _d === void 0 ? void 0 : _d.properties)
+                            ? flattenProperties(handler.schema.reqSchema.properties, handler.schema.reqSchema.required || [])
+                            : undefined,
+                        responseBody: ((_f = (_e = handler.schema) === null || _e === void 0 ? void 0 : _e.resSchema) === null || _f === void 0 ? void 0 : _f.properties)
+                            ? flattenProperties(handler.schema.resSchema.properties, handler.schema.resSchema.required || [])
+                            : undefined,
+                    });
+                });
+                // For WebSocket upgrade requests
+                if (req.headers.upgrade === "websocket") {
+                    // Handle WebSocket upgrade (requires additional WebSocket setup)
+                    res.status(426).send("WebSocket support not yet implemented");
+                    return [2 /*return*/];
+                }
+                // For regular HTTP requests to the MCP endpoint
+                if (req.method === "GET") {
+                    res.json({
+                        name: "api-docs-mcp-server",
+                        version: "1.0.0",
+                        description: "MCP server providing API documentation tools",
+                        tools: endpoints.length,
+                        endpoints: endpoints.map(function (e) { return ({
+                            path: e.path,
+                            method: e.method,
+                            description: e.description,
+                        }); }),
+                    });
+                    return [2 /*return*/];
+                }
+                // Handle MCP protocol messages over HTTP POST
+                if (req.method === "POST") {
+                    _a = req.body, method = _a.method, params = _a.params;
+                    // Handle tools/list
+                    if (method === "tools/list") {
+                        tools = endpoints.map(function (endpoint) { return ({
+                            name: "".concat(endpoint.method.toLowerCase(), "_").concat(endpoint.path.replace(/[/:]/g, "_")),
+                            description: endpoint.description || "".concat(endpoint.method, " ").concat(endpoint.path),
+                            inputSchema: generateInputSchema(endpoint),
+                        }); });
+                        res.json({ tools: tools });
+                        return [2 /*return*/];
+                    }
+                    // Handle tools/call
+                    if (method === "tools/call") {
+                        _b = params || {}, name_1 = _b.name, args = _b.arguments;
+                        endpoint = endpoints.find(function (e) { return "".concat(e.method.toLowerCase(), "_").concat(e.path.replace(/[/:]/g, "_")) === name_1; });
+                        if (!endpoint) {
+                            res.json({
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Tool not found: ".concat(name_1),
+                                    },
+                                ],
+                            });
+                            return [2 /*return*/];
+                        }
+                        response_1 = "Endpoint Details:\n";
+                        response_1 += "Path: ".concat(endpoint.path, "\n");
+                        response_1 += "Method: ".concat(endpoint.method, "\n");
+                        if (endpoint.description) {
+                            response_1 += "Description: ".concat(endpoint.description, "\n");
+                        }
+                        if (endpoint.pathParams && endpoint.pathParams.length > 0) {
+                            response_1 += "\nPath Parameters:\n";
+                            endpoint.pathParams.forEach(function (param) {
+                                response_1 += "- ".concat(param.name, ": ").concat(param.description || "No description", "\n");
+                            });
+                        }
+                        if (endpoint.queryParams && endpoint.queryParams.length > 0) {
+                            response_1 += "\nQuery Parameters:\n";
+                            endpoint.queryParams.forEach(function (param) {
+                                response_1 += "- ".concat(param.name).concat(param.required ? " (required)" : "", ": ").concat(param.type || "string", " - ").concat(param.description || "No description", "\n");
+                            });
+                        }
+                        if (endpoint.requestBody && endpoint.requestBody.length > 0) {
+                            response_1 += "\nRequest Body Schema:\n";
+                            response_1 += JSON.stringify(endpoint.requestBody, null, 2);
+                        }
+                        if (endpoint.responseBody && endpoint.responseBody.length > 0) {
+                            response_1 += "\nResponse Body Schema:\n";
+                            response_1 += JSON.stringify(endpoint.responseBody, null, 2);
+                        }
+                        res.json({
+                            content: [
+                                {
+                                    type: "text",
+                                    text: response_1,
+                                },
+                            ],
+                        });
+                        return [2 /*return*/];
+                    }
+                    res.status(400).json({
+                        error: "Unknown method",
+                        details: "Method ".concat(method, " is not supported"),
+                    });
+                    return [2 /*return*/];
+                }
+                res.status(405).send("Method not allowed");
+            }
+            catch (error) {
+                console.error("MCP handler error:", error);
+                res.status(500).send("Internal server error");
+            }
+            return [2 /*return*/];
+        });
+    }); };
+}
+exports.createMcpHandler = createMcpHandler;
+function generateInputSchema(endpoint) {
+    var inputSchema = {
+        type: "object",
+        properties: {},
+        required: [],
+    };
+    // Add path parameters
+    if (endpoint.pathParams && endpoint.pathParams.length > 0) {
+        endpoint.pathParams.forEach(function (param) {
+            inputSchema.properties[param.name] = {
+                type: "string",
+                description: param.description || "Path parameter: ".concat(param.name),
+            };
+            inputSchema.required.push(param.name);
+        });
+    }
+    // Add query parameters
+    if (endpoint.queryParams && endpoint.queryParams.length > 0) {
+        endpoint.queryParams.forEach(function (param) {
+            inputSchema.properties[param.name] = {
+                type: param.type || "string",
+                description: param.description || "Query parameter: ".concat(param.name),
+            };
+            if (param.required) {
+                inputSchema.required.push(param.name);
+            }
+        });
+    }
+    // Add request body
+    if (endpoint.requestBody && endpoint.requestBody.length > 0) {
+        var requestBodySchema_1 = {
+            type: "object",
+            properties: {},
+            required: [],
+        };
+        // Convert flat properties back to nested structure for schema
+        endpoint.requestBody.forEach(function (prop) {
+            var parts = prop.name.split(".");
+            var current = requestBodySchema_1.properties;
+            for (var i = 0; i < parts.length - 1; i++) {
+                var part = parts[i];
+                if (!current[part]) {
+                    current[part] = {
+                        type: "object",
+                        properties: {},
+                    };
+                }
+                current = current[part].properties;
+            }
+            var lastPart = parts[parts.length - 1];
+            current[lastPart] = {
+                type: prop.type,
+                description: prop.description,
+            };
+            if (prop.required) {
+                requestBodySchema_1.required.push(parts[0]);
+            }
+        });
+        inputSchema.properties.body = requestBodySchema_1;
+        inputSchema.required.push("body");
+    }
+    return inputSchema;
+}

package/dist/react-app/api-docs-favicon.svg

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="32px" height="32px" viewBox="0 0 32 32" version="1.1" xmlns="http://www.w3.org/2000/svg">
+    <title>API Docs Favicon</title>
+    <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <!-- Document outline -->
+        <path d="M6,2 L20,2 L26,8 L26,28 L6,28 Z" fill="#FFFFFF" stroke="#2563EB" stroke-width="2" />
+        <!-- Folded corner -->
+        <path d="M20,2 L20,8 L26,8 Z" fill="#E5E7EB" stroke="#2563EB" stroke-width="2" />
+        <!-- Document lines -->
+        <line x1="10" y1="14" x2="22" y2="14" stroke="#2563EB" stroke-width="2" />
+        <line x1="10" y1="18" x2="22" y2="18" stroke="#2563EB" stroke-width="2" />
+        <line x1="10" y1="22" x2="18" y2="22" stroke="#2563EB" stroke-width="2" />
+    </g>
+</svg>