// R-P5 (P5) — type-safe integration-adapter contract + registry (DoD #2). // // The Apps-Engine is "open": a new integration (Gmail, AirCall, Mollie, KWP, …) // is added by dropping an adapter under apps/web/app/integrations// that // registers an IntegrationAdapter here — NO core change. The platform-admin // surface (P19) shows a Klartext DRIFT warning when the registered adapters and // the App catalog disagree (checkCatalogDrift). // // This module is PURE (interface + an in-memory Map + a pure drift comparison) so // it lives in the foundation barrel. Concrete adapters do the network I/O; this // only declares the shape they must satisfy. Every adapter result is Klartext // (an i18n messageKey, M002/M003) — never a bare provider error. export type AdapterConnectionType = "oauth2" | "api_key" | "rest_api" | "windows_client"; /** Health verdict of a connection probe / credential validation. */ export type AdapterHealth = "active" | "degraded" | "broken"; /** Klartext result of validateConnection / healthCheck. */ export interface AdapterResult { readonly ok: boolean; readonly health: AdapterHealth; /** i18n key describing the state + next action (M002/M003). */ readonly messageKey: string; } /** One synced object reported by an adapter's sync(). */ export interface AdapterSyncItemResult { readonly entityType: string; readonly entityId?: string | null; readonly externalId: string; readonly operation: "created" | "updated" | "deleted" | "skipped"; readonly status: "synced" | "failed" | "skipped"; readonly errorText?: string | null; } /** Aggregate outcome of an adapter sync run. */ export interface AdapterSyncOutcome { readonly items: readonly AdapterSyncItemResult[]; /** i18n key for the run summary (Klartext). */ readonly summaryKey: string; } /** Result of refreshing an OAuth token. */ export interface AdapterTokenRefresh { readonly creds: Creds; readonly expiresAt: Date | null; } /** * The contract every integration must satisfy. `Creds` is the adapter-specific * decrypted credential shape (the engine handles envelope crypto + storage). */ export interface IntegrationAdapter> { readonly key: string; readonly connectionType: AdapterConnectionType; /** Validate freshly entered/authorised credentials (connect wizard). */ validateConnection(creds: Creds): Promise; /** Probe an existing connection's live health. */ healthCheck(creds: Creds): Promise; /** Refresh an expiring OAuth token (oauth2 adapters only). */ refreshToken?(creds: Creds): Promise>; /** Run a sync, returning per-item results for AppSyncRun aggregation. */ sync(creds: Creds): Promise; } const registry = new Map(); /** Register an integration adapter (idempotent by key; last registration wins). */ export function registerIntegrationAdapter(adapter: IntegrationAdapter): IntegrationAdapter { registry.set(adapter.key, adapter as IntegrationAdapter); return adapter; } /** Look up a registered adapter by key, or undefined. */ export function getIntegrationAdapter>(key: string): IntegrationAdapter | undefined { return registry.get(key) as IntegrationAdapter | undefined; } /** All registered adapter keys (sorted, for deterministic drift diffs). */ export function listIntegrationAdapterKeys(): string[] { return [...registry.keys()].sort(); } /** Test/registry reset hook. */ export function clearIntegrationAdapters(): void { registry.clear(); } /** A Klartext drift finding between the adapter registry and the App catalog. */ export interface CatalogDrift { /** Catalog Apps that have NO registered adapter (cannot connect). */ readonly missingAdapters: readonly string[]; /** Registered adapters with NO catalog App (orphan; won't appear in the UI). */ readonly orphanAdapters: readonly string[]; /** True when the registry and catalog fully agree. */ readonly inSync: boolean; } /** * Pure drift comparison: the registered adapter keys vs. the App-catalog keys. * The platform admin renders a Klartext warning when `inSync` is false. Build * time can run the same check (scripts/scan-integrations.mjs) to fail fast. */ export function checkCatalogDrift(adapterKeys: readonly string[], catalogKeys: readonly string[]): CatalogDrift { const adapters = new Set(adapterKeys); const catalog = new Set(catalogKeys); const missingAdapters = [...catalog].filter((key) => !adapters.has(key)).sort(); const orphanAdapters = [...adapters].filter((key) => !catalog.has(key)).sort(); return { missingAdapters, orphanAdapters, inSync: missingAdapters.length === 0 && orphanAdapters.length === 0 }; }