@digitalpaws/starr 0.0.1

package/src/web/routes/config.ts

@@ -0,0 +1,282 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { ConfigService } from "../../config/config-service.js";
+import type { ConfigField } from "../../types/plugin.js";
+import { SECRET_UNCHANGED_SENTINEL } from "../../config/config-service.js";
+import type { PluginRuntime } from "../../host.js";
+
+let configService: ConfigService | null = null;
+let getRuntimes: (() => readonly PluginRuntime[]) | null = null;
+
+export function initConfigRoutes(
+  cs: ConfigService,
+  runtimeGetter: () => readonly PluginRuntime[],
+): void {
+  configService = cs;
+  getRuntimes = runtimeGetter;
+}
+
+function requireAdmin(request: any, reply: any): boolean {
+  const user = (request as any).user;
+  if (!user || user.role !== "admin") {
+    reply.status(403).send({ error: "Forbidden: admin role required" });
+    return false;
+  }
+  return true;
+}
+
+const configRoutes: FastifyPluginAsync = async (server) => {
+  // GET /api/config — list all plugin config summaries
+  server.get("/api/config", async (request, reply) => {
+    if (!requireAdmin(request, reply)) return;
+    if (!configService) {
+      return { plugins: [] };
+    }
+    return { plugins: configService.list() };
+  });
+
+  // GET /api/config/:pluginId — get single plugin config (or instance if ?instanceId=)
+  server.get<{ Params: { pluginId: string }; Querystring: { instanceId?: string } }>(
+    "/api/config/:pluginId",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const instanceId = request.query.instanceId ?? "default";
+      const entry = configService.get(request.params.pluginId, instanceId);
+      if (!entry) {
+        reply.status(404).send({ error: "plugin/instance not found" });
+        return;
+      }
+
+      // Find runtime for this instance
+      const fullId = instanceId === "default"
+        ? request.params.pluginId
+        : `${request.params.pluginId}::${instanceId}`;
+      const runtime = getRuntimes?.().find(
+        (r) => r.meta.id === fullId,
+      );
+
+      return {
+        ...entry,
+        instanceId,
+        supportsTest: !!runtime?.lifecycle.testConnection,
+      };
+    },
+  );
+
+  // PUT /api/config/:pluginId — update config (optional ?instanceId=)
+  server.put<{
+    Params: { pluginId: string };
+    Querystring: { instanceId?: string };
+    Body: Record<string, unknown>;
+  }>(
+    "/api/config/:pluginId",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const instanceId = request.query.instanceId ?? "default";
+      const entry = configService.get(request.params.pluginId, instanceId);
+      if (!entry) {
+        reply.status(404).send({ error: "plugin/instance not found" });
+        return;
+      }
+
+      const result = configService.update(
+        request.params.pluginId,
+        entry.schema,
+        request.body,
+        instanceId,
+      );
+
+      if (!result.valid) {
+        reply.status(400).send({ errors: result.errors });
+        return;
+      }
+
+      return { ok: true };
+    },
+  );
+
+  // GET /api/config/:pluginId/instances — list all instances for a plugin
+  server.get<{ Params: { pluginId: string } }>(
+    "/api/config/:pluginId/instances",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const instances = configService.listInstances(request.params.pluginId);
+      return { instances };
+    },
+  );
+
+  // POST /api/config/:pluginId/instances — create a new instance
+  server.post<{
+    Params: { pluginId: string };
+    Body: { instanceId: string; values: Record<string, unknown> };
+  }>(
+    "/api/config/:pluginId/instances",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const { pluginId } = request.params;
+      const { instanceId, values } = request.body;
+
+      if (!instanceId || typeof instanceId !== "string") {
+        reply.status(400).send({ error: "instanceId is required" });
+        return;
+      }
+
+      // Get the schema from the default instance (or any existing instance)
+      const defaultEntry = configService.get(pluginId, "default");
+      if (!defaultEntry) {
+        reply.status(404).send({ error: "plugin not found; configure the default instance first" });
+        return;
+      }
+
+      const result = configService.createInstance(
+        pluginId,
+        instanceId,
+        defaultEntry.schema,
+        values,
+      );
+
+      if (!result.valid) {
+        reply.status(400).send({ errors: result.errors });
+        return;
+      }
+
+      reply.status(201).send({
+        pluginId,
+        instanceId,
+        values: result.values,
+      });
+    },
+  );
+
+  // DELETE /api/config/:pluginId/instances/:instanceId — delete an instance
+  server.delete<{
+    Params: { pluginId: string; instanceId: string };
+    Querystring: { force?: string };
+  }>(
+    "/api/config/:pluginId/instances/:instanceId",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const { pluginId, instanceId } = request.params;
+
+      try {
+        // If not force, check if instance has libraryId set (downloader connection)
+        if (request.query.force !== "true") {
+          const entry = configService.get(pluginId, instanceId);
+          if (entry?.values?.libraryId) {
+            reply.status(400).send({
+              error: `Instance "${instanceId}" is connected to library "${entry.values.libraryId}". Use ?force=true to disconnect and delete, or clear the libraryId first.`,
+            });
+            return;
+          }
+        }
+
+        configService.deleteInstance(pluginId, instanceId);
+        return { deleted: true };
+      } catch (err: any) {
+        reply.status(400).send({ error: err.message });
+      }
+    },
+  );
+
+  // POST /api/config/:pluginId/test — test connection without saving (optional ?instanceId=)
+  server.post<{
+    Params: { pluginId: string };
+    Querystring: { instanceId?: string };
+    Body: Record<string, unknown>;
+  }>(
+    "/api/config/:pluginId/test",
+    async (request, reply) => {
+      if (!requireAdmin(request, reply)) return;
+      if (!configService) {
+        reply.status(500).send({ error: "config service not available" });
+        return;
+      }
+
+      const instanceId = request.query.instanceId ?? "default";
+      const entry = configService.get(request.params.pluginId, instanceId);
+      if (!entry) {
+        reply.status(404).send({ error: "plugin/instance not found" });
+        return;
+      }
+
+      // Resolve secret sentinels without validating the body
+      const decrypted = configService.getDecryptedValues(request.params.pluginId, instanceId);
+      const testValues = { ...request.body };
+      for (const [key, rawField] of Object.entries(entry.schema)) {
+        const field = rawField as ConfigField;
+        if (field.type === "secret" && testValues[key] === SECRET_UNCHANGED_SENTINEL) {
+          if (!decrypted || decrypted[key] === undefined) {
+            reply.status(400).send({
+              error: `Secret field "${key}" is required to run the test`,
+            });
+            return;
+          }
+          testValues[key] = decrypted[key];
+        }
+      }
+
+      // Find the plugin runtime for this instance
+      const fullId = instanceId === "default"
+        ? request.params.pluginId
+        : `${request.params.pluginId}::${instanceId}`;
+      const runtime = getRuntimes?.().find(
+        (r) => r.meta.id === fullId,
+      );
+
+      if (!runtime?.lifecycle.testConnection) {
+        reply.status(400).send({
+          error: "Plugin does not support connection tests",
+        });
+        return;
+      }
+
+      try {
+        const result = await runtime.lifecycle.testConnection(testValues);
+        return result;
+      } catch (err) {
+        // Sanitize: mask any secret values in the error message
+        let sanitizedError =
+          err instanceof Error ? err.message : String(err);
+        for (const val of Object.values(testValues)) {
+          if (typeof val === "string" && val.length > 0) {
+            sanitizedError = sanitizedError.replaceAll(val, "***");
+          }
+        }
+        reply.status(500).send({
+          ok: false,
+          message: sanitizedError,
+        });
+        return;
+      }
+    },
+  );
+};
+
+export default configRoutes;

package/src/web/routes/content-types.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { ContentTypeDescriptor } from "@digitalpaws/starr-types-core";
+
+/**
+ * This module needs access to the host's content-type registry.
+ * We provide it via module-level setters called from main.ts.
+ */
+let getDescriptors: () => ContentTypeDescriptor[] = () => [];
+let getDescriptor: (id: string) => ContentTypeDescriptor | undefined = () => undefined;
+
+export function initContentTypeRoutes(
+  listFn: () => ContentTypeDescriptor[],
+  getFn: (id: string) => ContentTypeDescriptor | undefined,
+): void {
+  getDescriptors = listFn;
+  getDescriptor = getFn;
+}
+
+const contentTypeRoutes: FastifyPluginAsync = async (server) => {
+  // GET /api/content-types
+  server.get("/api/content-types", async (_request, _reply) => {
+    return { types: getDescriptors() };
+  });
+
+  // GET /api/content-types/:id
+  server.get<{ Params: { id: string } }>(
+    "/api/content-types/:id",
+    async (request, reply) => {
+      const desc = getDescriptor(request.params.id);
+      if (!desc) {
+        reply.status(404).send({ error: "content type not found" });
+        return;
+      }
+      return desc;
+    },
+  );
+};
+
+export default contentTypeRoutes;

package/src/web/routes/discovery.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { EventBus, Unsubscribe, StarrEvent } from "../../types/plugin.js";
+import type { ContentItemBase } from "@digitalpaws/starr-types-core";
+
+let eventBus: EventBus | null = null;
+
+export function initDiscoveryRoutes(bus: EventBus): void {
+  eventBus = bus;
+}
+
+const DEFAULT_WINDOW_MS = 10000;
+
+const LOOKUP_TIMEOUT_MS = 5000;
+
+function discoveryWindowMs(): number {
+  return parseInt(process.env.STARR_DISCOVERY_WINDOW_MS ?? String(DEFAULT_WINDOW_MS), 10);
+}
+
+const discoveryRoutes: FastifyPluginAsync = async (server) => {
+  server.get<{
+    Querystring: {
+      q?: string;
+      type?: string;       // comma-separated contentTypeIds
+      offset?: string;
+      limit?: string;
+    };
+  }>(
+    "/api/discovery/search",
+    async (request, reply) => {
+      if (!eventBus) {
+        reply.status(500).send({ error: "event bus not available" });
+        return;
+      }
+
+      const query = request.query.q ?? "";
+      const contentTypeIds = request.query.type
+        ? request.query.type.split(",").filter(Boolean)
+        : undefined;
+      const offset = parseInt(request.query.offset ?? "0", 10) || 0;
+      const limit = parseInt(request.query.limit ?? "20", 10) || 20;
+
+      try {
+        // discovery.results is a broadcast reply (multiple metadata plugins
+        // may respond). Collect every result that arrives during the window.
+        const allItems: ContentItemBase[] = [];
+
+        const collectPromise = new Promise<Unsubscribe>((resolve) => {
+          const unsubscribe = eventBus!.on("discovery.results", (event: StarrEvent<{ contentTypeId: string; items: ContentItemBase[] }>) => {
+            allItems.push(...event.payload.items);
+          });
+          const windowMs = discoveryWindowMs();
+          setTimeout(() => resolve(unsubscribe), windowMs);
+        });
+
+        eventBus.emit("discovery.search", {
+          query,
+          contentTypeIds,
+          offset,
+          limit,
+        });
+
+        const unsubscribe = await collectPromise;
+        unsubscribe();
+
+        // Apply offset/limit client-side (plugins may not all respect it)
+        const paged = allItems.slice(offset, offset + limit);
+
+        return {
+          items: paged,
+          total: allItems.length,
+          offset,
+          limit,
+        };
+      } catch (err: any) {
+        reply.status(500).send({ error: String(err) });
+      }
+    },
+  );
+
+  // GET /api/discovery/lookup — return a single item by content type + external IDs
+  server.get<{
+    Querystring: {
+      contentTypeId: string;
+      externalIds: string;  // JSON-encoded Record<string, string>
+    };
+  }>(
+    "/api/discovery/lookup",
+    async (request, reply) => {
+      if (!eventBus) {
+        reply.status(500).send({ error: "event bus not available" });
+        return;
+      }
+
+      const { contentTypeId, externalIds: rawExt } = request.query;
+      let externalIds: Record<string, string>;
+      try {
+        externalIds = JSON.parse(rawExt);
+      } catch {
+        reply.status(400).send({ error: "externalIds must be valid JSON" });
+        return;
+      }
+
+      if (!contentTypeId || !externalIds || Object.keys(externalIds).length === 0) {
+        reply.status(400).send({ error: "contentTypeId and externalIds are required" });
+        return;
+      }
+
+      try {
+        // Emit a discovery.lookup broadcast — metadata plugins respond with the item
+        let foundItem: ContentItemBase | null = null;
+
+        const collectPromise = new Promise<Unsubscribe>((resolve) => {
+          const unsubscribe = eventBus!.on(
+            "discovery.lookup.result",
+            (event: StarrEvent<{ contentTypeId: string; items: ContentItemBase[] }>) => {
+              // Take the first match that satisfies our external IDs
+              for (const item of event.payload.items) {
+                if (item.contentTypeId !== contentTypeId) continue;
+                const matches = Object.entries(externalIds).every(
+                  ([key, val]) => item.externalIds?.[key] === val,
+                );
+                if (matches) {
+                  foundItem = item;
+                }
+              }
+            },
+          );
+          // Timed timeout for metadata plugins to respond
+          setTimeout(() => resolve(unsubscribe), LOOKUP_TIMEOUT_MS);
+        });
+
+        eventBus.emit("discovery.lookup", {
+          contentTypeId,
+          externalIds,
+        });
+
+        const unsubscribe = await collectPromise;
+        unsubscribe();
+
+        if (!foundItem) {
+          reply.status(404).send({ error: "item not found" });
+          return;
+        }
+
+        return foundItem;
+      } catch (err: any) {
+        reply.status(500).send({ error: String(err) });
+      }
+    },
+  );
+};
+
+export default discoveryRoutes;

package/src/web/routes/library-import.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { ScanController } from "../../library/scan-controller.js";
+
+let controller: ScanController | null = null;
+
+export function initLibraryImportRoutes(sc: ScanController): void {
+  controller = sc;
+}
+
+const libraryImportRoutes: FastifyPluginAsync = async (server) => {
+  // POST /api/library/scan — start a new scan
+  server.post<{
+    Body: {
+      libraryId?: string;
+      contentTypeIds?: string[];
+    };
+  }>(
+    "/api/library/scan",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const { libraryId, contentTypeIds } = request.body ?? {};
+      const scanId = controller.startScan(libraryId, contentTypeIds);
+
+      reply.status(201).send({ scanId });
+    },
+  );
+
+  // GET /api/library/scan/:scanId — get scan progress/results
+  server.get<{
+    Params: { scanId: string };
+  }>(
+    "/api/library/scan/:scanId",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const state = controller.getScan(request.params.scanId);
+      if (!state) {
+        reply.status(404).send({ error: "scan not found" });
+        return;
+      }
+
+      return {
+        scanId: state.scanId,
+        status: state.status,
+        progress: state.progress,
+        candidates: state.candidates,
+      };
+    },
+  );
+
+  // POST /api/library/scan/:scanId/import — import selected candidates
+  server.post<{
+    Params: { scanId: string };
+    Body: {
+      candidateIds: string[];
+    };
+  }>(
+    "/api/library/scan/:scanId/import",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const state = controller.getScan(request.params.scanId);
+      if (!state) {
+        reply.status(404).send({ error: "scan not found" });
+        return;
+      }
+
+      if (state.status !== "complete") {
+        reply.status(409).send({ error: "scan is not yet complete" });
+        return;
+      }
+
+      const { candidateIds } = request.body ?? {};
+      if (!Array.isArray(candidateIds) || candidateIds.length === 0) {
+        reply.status(400).send({ error: "candidateIds must be a non-empty array" });
+        return;
+      }
+
+      const result = await controller.importCandidates(request.params.scanId, candidateIds);
+
+      return result;
+    },
+  );
+
+  // POST /api/library/scan/:scanId/candidate/:candidateId/search — custom search for a candidate
+  server.post<{
+    Params: { scanId: string; candidateId: string };
+    Body: { query: string };
+  }>(
+    "/api/library/scan/:scanId/candidate/:candidateId/search",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const { query } = request.body ?? {};
+      if (!query || query.trim().length === 0) {
+        reply.status(400).send({ error: "query is required" });
+        return;
+      }
+
+      const ok = await controller.searchCandidate(
+        request.params.scanId,
+        request.params.candidateId,
+        query,
+      );
+
+      if (!ok) {
+        reply.status(404).send({ error: "candidate not found" });
+        return;
+      }
+
+      // Return updated scan state so the UI can refresh
+      const state = controller.getScan(request.params.scanId);
+      return {
+        scanId: state?.scanId,
+        status: state?.status,
+        progress: state?.progress,
+        candidates: state?.candidates,
+      };
+    },
+  );
+
+  // POST /api/library/scan/:scanId/candidate/:candidateId/select — pick a match
+  server.post<{
+    Params: { scanId: string; candidateId: string };
+    Body: { matchIndex: number };
+  }>(
+    "/api/library/scan/:scanId/candidate/:candidateId/select",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const { matchIndex } = request.body ?? {};
+      if (typeof matchIndex !== "number" || matchIndex < -1) {
+        reply.status(400).send({ error: "matchIndex must be a number >= -1" });
+        return;
+      }
+
+      const ok = controller.selectMatch(
+        request.params.scanId,
+        request.params.candidateId,
+        matchIndex,
+      );
+
+      if (!ok) {
+        reply.status(404).send({ error: "candidate or invalid matchIndex" });
+        return;
+      }
+
+      const state = controller.getScan(request.params.scanId);
+      return {
+        scanId: state?.scanId,
+        status: state?.status,
+        progress: state?.progress,
+        candidates: state?.candidates,
+      };
+    },
+  );
+
+  // DELETE /api/library/scan/:scanId — cancel a scan and clean up
+  server.delete<{
+    Params: { scanId: string };
+  }>(
+    "/api/library/scan/:scanId",
+    async (request, reply) => {
+      if (!controller) {
+        reply.status(500).send({ error: "scan controller not available" });
+        return;
+      }
+
+      const cancelled = controller.cancelScan(request.params.scanId);
+      controller.cleanupScan(request.params.scanId);
+
+      return { cancelled };
+    },
+  );
+};
+
+export default libraryImportRoutes;