Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/foundation/src/integration-adapters.ts
T
2026-07-08 16:15:37 +02:00

112 lines
4.7 KiB
TypeScript

// 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/<key>/ 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<Creds> {
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<Creds = Record<string, unknown>> {
readonly key: string;
readonly connectionType: AdapterConnectionType;
/** Validate freshly entered/authorised credentials (connect wizard). */
validateConnection(creds: Creds): Promise<AdapterResult>;
/** Probe an existing connection's live health. */
healthCheck(creds: Creds): Promise<AdapterResult>;
/** Refresh an expiring OAuth token (oauth2 adapters only). */
refreshToken?(creds: Creds): Promise<AdapterTokenRefresh<Creds>>;
/** Run a sync, returning per-item results for AppSyncRun aggregation. */
sync(creds: Creds): Promise<AdapterSyncOutcome>;
}
const registry = new Map<string, IntegrationAdapter>();
/** Register an integration adapter (idempotent by key; last registration wins). */
export function registerIntegrationAdapter<Creds>(adapter: IntegrationAdapter<Creds>): IntegrationAdapter<Creds> {
registry.set(adapter.key, adapter as IntegrationAdapter);
return adapter;
}
/** Look up a registered adapter by key, or undefined. */
export function getIntegrationAdapter<Creds = Record<string, unknown>>(key: string): IntegrationAdapter<Creds> | undefined {
return registry.get(key) as IntegrationAdapter<Creds> | 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 };
}