Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
+111
@@ -0,0 +1,111 @@
|
||||
// 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 };
|
||||
}
|
||||
Reference in new issue
Block a user