feat: plugins v1

2026-04-29 01:14:14 +02:00
parent ec3802ade6
commit 6920f93b41
86 changed files with 9036 additions and 14 deletions
--- a/server/src/routes/openapi-docs.ts
+++ b/server/src/routes/openapi-docs.ts
@@ -0,0 +1,106 @@
+import { Router } from 'express';
+import { areOpenApiDocsEnabled, setOpenApiDocsEnabled } from '../config/variables';
+
+const router = Router();
+
+function createOpenApiDocument(baseUrl: string) {
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: 'MetoYou Plugin Support API',
+      version: '1.0.0',
+      description: 'Official HTTP endpoints for plugin metadata, event definitions, and plugin data. '
+        + 'Plugin code is never executed by the signal server.'
+    },
+    servers: [{ url: `${baseUrl}/api` }],
+    paths: {
+      '/servers/{serverId}/plugins': {
+        get: {
+          summary: 'Read plugin requirement snapshot',
+          parameters: [{ name: 'serverId', in: 'path', required: true, schema: { type: 'string' } }],
+          responses: { '200': { description: 'Plugin requirements and event definitions' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/requirement': {
+        put: {
+          summary: 'Create or update a server plugin requirement',
+          responses: { '200': { description: 'Requirement saved' }, '403': { description: 'Not authorized' } }
+        },
+        delete: {
+          summary: 'Delete a server plugin requirement',
+          responses: { '200': { description: 'Requirement deleted' }, '403': { description: 'Not authorized' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/events/{eventName}': {
+        put: {
+          summary: 'Create or update a plugin event definition',
+          responses: { '200': { description: 'Event definition saved' }, '403': { description: 'Not authorized' } }
+        },
+        delete: {
+          summary: 'Delete a plugin event definition',
+          responses: { '200': { description: 'Event definition deleted' }, '403': { description: 'Not authorized' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/data': {
+        get: {
+          summary: 'List plugin data records',
+          responses: { '200': { description: 'Plugin data records' }, '403': { description: 'Not a server member' } }
+        }
+      },
+      '/servers/{serverId}/plugins/{pluginId}/data/{key}': {
+        put: {
+          summary: 'Write plugin data',
+          responses: { '200': { description: 'Plugin data saved' }, '403': { description: 'Not a server member' } }
+        },
+        delete: {
+          summary: 'Delete plugin data',
+          responses: { '200': { description: 'Plugin data deleted' }, '403': { description: 'Not a server member' } }
+        }
+      },
+      '/openapi/settings': {
+        get: { summary: 'Read OpenAPI docs setting', responses: { '200': { description: 'Setting value' } } },
+        put: { summary: 'Toggle OpenAPI docs exposure', responses: { '200': { description: 'Setting value' } } }
+      }
+    }
+  };
+}
+
+function docsDisabledResponse() {
+  return { error: 'OpenAPI docs are disabled', errorCode: 'OPENAPI_DOCS_DISABLED' };
+}
+
+router.get('/openapi/settings', (_req, res) => {
+  res.json({ enabled: areOpenApiDocsEnabled() });
+});
+
+router.put('/openapi/settings', (req, res) => {
+  res.json(setOpenApiDocsEnabled(req.body?.enabled === true));
+});
+
+router.get('/openapi.json', (req, res) => {
+  if (!areOpenApiDocsEnabled()) {
+    res.status(404).json(docsDisabledResponse());
+    return;
+  }
+
+  res.json(createOpenApiDocument(`${req.protocol}://${req.get('host') ?? 'localhost'}`));
+});
+
+router.get('/docs', (_req, res) => {
+  if (!areOpenApiDocsEnabled()) {
+    res.status(404).json(docsDisabledResponse());
+    return;
+  }
+
+  res.type('html').send(`<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>MetoYou Plugin API Docs</title></head>
+<body style="font-family:system-ui;margin:2rem;line-height:1.5">
+<h1>MetoYou Plugin Support API</h1>
+<p>Plugin support endpoints are available at <a href="/api/openapi.json">/api/openapi.json</a>.</p>
+<p>The signal server stores metadata, data, and event definitions only. It never executes plugin code.</p>
+</body>
+</html>`);
+});
+
+export default router;