refactor(api): split integration-host.ts into focused modules

Extract three concerns out of the 1518-line integration-host.ts into
dedicated modules, leaving the host as a thin façade:

- integration-clients.ts: createHttpClient, createCacheClient,
  createLiveStoreClient, createLogger (pure context client factories)
- integration-config.ts: resolveConfigWithSources, resolveConfig,
  warnInvalidConfig, ConfigSource/ConfigValueWithSource types
- integration-routes.ts: mini-router machinery — registerIntegrationRoute,
  resetIntegrationRoutes, registerIntegrationRouteDispatcher + state

Zero behavior change. resolveConfigWithSources re-exported from host so
routes/admin.ts and its test remain byte-for-byte unchanged.
registerIntegrationRouteDispatcher takes an explicit integrations Map
parameter to avoid a static import cycle.

Plan 002 characterization tests (16/16) pass unmodified.

Author: Medformatik

apps/api/src/integration-clients.ts

@@ -0,0 +1,118 @@
+import type {
+  CacheClient,
+  HttpClient,
+  HttpClientOptions,
+  LiveStoreClient,
+  Logger,
+} from "@openmapx/integration-framework";
+import type { FastifyInstance } from "fastify";
+import { redis } from "./redis";
+import { httpCacheKey } from "./utils/http-cache-key";
+import { createIntegrationLogger } from "./utils/integration-logger";
+
+export function createHttpClient(_log: Logger): HttpClient {
+  return {
+    async get<T>(url: string, options?: HttpClientOptions): Promise<T> {
+      const u = new URL(url);
+      if (options?.params) {
+        for (const [k, v] of Object.entries(options.params)) {
+          if (v !== undefined) u.searchParams.set(k, String(v));
+        }
+      }
+
+      if (options?.cache?.ttl && redis) {
+        const cacheKey = httpCacheKey(u.toString(), options?.headers);
+        try {
+          const cached = await redis.get(cacheKey);
+          if (cached) return JSON.parse(cached) as T;
+        } catch {
+          // cache miss
+        }
+
+        const res = await fetch(u.toString(), { headers: options?.headers });
+        if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        const data = (await res.json()) as T;
+        redis.setex(cacheKey, options.cache.ttl, JSON.stringify(data)).catch(() => {});
+        return data;
+      }
+
+      const res = await fetch(u.toString(), { headers: options?.headers });
+      if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      return (await res.json()) as T;
+    },
+
+    async post<T>(url: string, body?: unknown, options?: HttpClientOptions): Promise<T> {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...options?.headers },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      return (await res.json()) as T;
+    },
+  };
+}
+
+export function createCacheClient(prefix: string): CacheClient {
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      if (!redis) return null;
+      const val = await redis.get(`int:${prefix}:${key}`);
+      return val ? (JSON.parse(val) as T) : null;
+    },
+    async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+      if (!redis) return;
+      const k = `int:${prefix}:${key}`;
+      if (ttlSeconds) {
+        await redis.setex(k, ttlSeconds, JSON.stringify(value));
+      } else {
+        await redis.set(k, JSON.stringify(value));
+      }
+    },
+    async del(key: string): Promise<void> {
+      if (!redis) return;
+      await redis.del(`int:${prefix}:${key}`);
+    },
+    async withCache<T>(key: string, ttlSeconds: number, fn: () => Promise<T>): Promise<T> {
+      if (redis) {
+        const k = `int:${prefix}:${key}`;
+        try {
+          const cached = await redis.get(k);
+          if (cached) return JSON.parse(cached) as T;
+        } catch {
+          // cache miss
+        }
+        const result = await fn();
+        redis.setex(k, ttlSeconds, JSON.stringify(result)).catch(() => {});
+        return result;
+      }
+      return fn();
+    },
+  };
+}
+
+/**
+ * Reader for the cross-process `poi:live:<sourceId>` keyspace that
+ * `services/data-manager`'s `write-live` stage populates. The keys are
+ * deliberately NOT integration-namespaced — data-manager has no notion of
+ * integration ids, only the source ids in `@openmapx/poi-source-registry`.
+ * Prefixing here would silently miss every write.
+ *
+ * Process-scoped (one client shared across all integrations); per-key
+ * isolation already happens via `@openmapx/poi-source-registry` ensuring
+ * source ids are globally unique.
+ */
+export function createLiveStoreClient(): LiveStoreClient {
+  return {
+    async hmget<T>(key: string, fields: readonly string[]): Promise<(T | null)[]> {
+      if (!redis) return fields.map(() => null);
+      if (fields.length === 0) return [];
+      const values = await redis.hmget(key, ...fields);
+      return values.map((v) => (v ? (JSON.parse(v) as T) : null));
+    },
+  };
+}
+
+export function createLogger(integrationId: string, fastify: FastifyInstance): Logger {
+  return createIntegrationLogger(integrationId, fastify);
+}

apps/api/src/integration-config.ts

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { IntegrationManifest } from "@openmapx/integration-framework";
+import { eq } from "drizzle-orm";
+import { db } from "./db";
+import { integrationConfig } from "./db/schema";
+import { resolveVaultSecrets } from "./services/secrets";
+
+export type ConfigSource = "default" | "database" | "vault" | "config.json" | "env";
+
+export interface ConfigValueWithSource {
+  value: unknown;
+  source: ConfigSource;
+}
+
+export async function resolveConfigWithSources(
+  manifest: IntegrationManifest,
+  directory: string,
+): Promise<Record<string, ConfigValueWithSource>> {
+  const result: Record<string, ConfigValueWithSource> = {};
+  const schema = manifest.configSchema as Record<string, unknown> | undefined;
+  const knownKeys = new Set<string>();
+  // Uppercased config key → canonical (original-case) key. Used to match env
+  // vars like `INTEGRATION_PHOTOS_FLICKR_APIKEY` against configSchema key
+  // `apiKey` without forcing operators to lowercase the suffix (or forcing
+  // schema authors to pick all-lowercase keys).
+  const upperToKey = new Map<string, string>();
+
+  if (schema) {
+    const props = (schema.properties ?? schema) as Record<string, { default?: unknown }>;
+    for (const [key, def] of Object.entries(props)) {
+      if (key === "type" || key === "properties") continue;
+      knownKeys.add(key);
+      upperToKey.set(key.toUpperCase(), key);
+      if (def && typeof def === "object" && "default" in def && def.default !== undefined) {
+        result[key] = { value: def.default, source: "default" };
+      }
+    }
+  }
+
+  if (knownKeys.size === 0) return result;
+
+  try {
+    const [row] = await db
+      .select({ config: integrationConfig.config })
+      .from(integrationConfig)
+      .where(eq(integrationConfig.integrationId, manifest.id))
+      .limit(1);
+    if (row?.config && typeof row.config === "object") {
+      for (const [key, value] of Object.entries(row.config as Record<string, unknown>)) {
+        if (knownKeys.has(key)) result[key] = { value, source: "database" };
+      }
+    }
+  } catch {
+    // DB not available
+  }
+
+  // 3. Apply vault secrets
+  try {
+    const vaultSecrets = await resolveVaultSecrets(manifest.id);
+    for (const [key, value] of Object.entries(vaultSecrets)) {
+      if (knownKeys.has(key)) result[key] = { value, source: "vault" };
+    }
+  } catch {
+    // vault unavailable
+  }
+
+  const configJsonPath = join(directory, "config.json");
+  if (existsSync(configJsonPath)) {
+    try {
+      const fileConfig = JSON.parse(readFileSync(configJsonPath, "utf-8"));
+      if (typeof fileConfig === "object" && fileConfig !== null) {
+        for (const [key, value] of Object.entries(fileConfig as Record<string, unknown>)) {
+          if (knownKeys.has(key)) result[key] = { value, source: "config.json" };
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Env layer — highest priority. Pattern: `INTEGRATION_<ID>_<KEY>` (upper-cased
+  // id with hyphens replaced by underscores, then the upper-cased config key).
+  // Matching is case-insensitive on the configSchema key so both snake_case
+  // and camelCase keys work (`apiKey` matches `INTEGRATION_X_APIKEY`).
+  const prefix = `INTEGRATION_${manifest.id.replace(/-/g, "_").toUpperCase()}_`;
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (envVal === undefined) continue;
+    if (!envKey.startsWith(prefix)) continue;
+    const rest = envKey.slice(prefix.length);
+    const canonical = upperToKey.get(rest);
+    if (canonical) result[canonical] = { value: envVal, source: "env" };
+  }
+
+  return result;
+}
+
+export async function resolveConfig(
+  manifest: {
+    id: string;
+    configSchema?: Record<string, unknown>;
+  },
+  directory: string,
+): Promise<Record<string, unknown>> {
+  const withSources = await resolveConfigWithSources(manifest as IntegrationManifest, directory);
+  const config: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(withSources)) {
+    config[key] = entry.value;
+  }
+  return config;
+}
+
+/**
+ * Emits advisory warnings for required/enum config keys that violate the
+ * manifest's `configSchema`. Never blocks load. Shared by cold start and reload.
+ */
+export function warnInvalidConfig(
+  manifest: IntegrationManifest,
+  config: Record<string, unknown>,
+  id: string,
+  warn: (msg: string) => void,
+): void {
+  const configSchema = manifest.configSchema as Record<string, unknown> | undefined;
+  if (!configSchema?.properties) return;
+  const props = configSchema.properties as Record<
+    string,
+    { type?: string; enum?: unknown[]; required?: boolean }
+  >;
+  for (const [key, def] of Object.entries(props)) {
+    if (def.required && config[key] === undefined) {
+      warn(`Integration ${id}: missing required config key "${key}"`);
+    }
+    if (def.enum && config[key] !== undefined && !def.enum.includes(config[key])) {
+      warn(
+        `Integration ${id}: config "${key}" value "${config[key]}" not in allowed values: ${def.enum.join(", ")}`,
+      );
+    }
+  }
+}