Implement Integration Config Service CRUD orchestration
epic-external-system-integration-configuration-core-services-task-010 — Build the Integration Config Service that orchestrates all CRUD operations for integration configurations. Implements create, read, update, delete with uniqueness enforcement (one active config per org per integration type), transactional saves with rollback, and event emission on configuration changes. Coordinates with credential vault and repository layers.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Handles integration between different epics or system components. Requires coordination across multiple development streams.
Implementation Notes
Implement as a Deno TypeScript service class (IntegrationConfigService) inside a Supabase Edge Function module. The most critical design concern is the two-phase transaction: Supabase PostgreSQL supports real transactions via the database, but the credential vault is a separate system. Implement a saga pattern: (1) write config to DB in a transaction, (2) write credential to vault, (3) commit transaction. On vault write failure, explicitly call transaction ROLLBACK.
Use Supabase's supabase-js v2 client with `.rpc()` for database transactions or raw SQL via `pg` client for explicit transaction control. For the credential vault, if it is implemented as an encrypted Supabase table (from task-002), wrap both writes in a single Postgres transaction using a stored procedure — this gives true atomicity without a saga. For event emission, use Supabase Realtime broadcast channel (not database changes) to control the payload shape — this prevents credential fields from accidentally leaking through database change events. Use a typed EventEmitter helper that constructs the safe payload before broadcasting.
The service should depend on the IntegrationConfigRepository (task-002) and CredentialVault interfaces via constructor injection — this makes unit testing straightforward without live database connections.
Testing Requirements
Unit tests (Deno test): createIntegrationConfig happy path with mock repository and mock credential vault, rollback when vault write fails (database row must not exist after rollback), rollback when database write fails (vault write must not have been attempted), readIntegrationConfig returns config without credential values, listIntegrationConfigs returns all active configs for org, updateIntegrationConfig with and without credential rotation, deleteIntegrationConfig soft-deletes and triggers vault credential removal, event emission verified for all three mutation operations, cross-org access rejection for all five methods. Integration tests: full create-read-update-delete cycle against a test Supabase instance. Test coverage target: 95% on service layer logic. All tests must be deterministic — mock Realtime channel to avoid side effects.
Each of the five external systems (Xledger, Dynamics, Cornerstone, Consio, Bufdir) has a different authentication flow, field schema, and error format. Forcing them into a uniform adapter interface may require compromises that result in leaky abstractions or make the adapter contract too complex to maintain.
Mitigation & Contingency
Mitigation: Design the IntegrationAdapter interface with a loose invoke() payload rather than a typed one, allowing each adapter to declare its own input/output schema. Use integration type metadata in the registry to document per-adapter quirks. Build Xledger first as the most documented API, then adapt the interface based on learnings.
Contingency: If the uniform interface cannot accommodate all five systems, split into two interface tiers: a simple polling/export adapter and a richer bidirectional adapter, with the registry declaring which tier each system implements.
Development and testing of the Cornerstone and Consio adapters depends on NHF providing sandbox API access. If credentials or documentation are delayed, these adapters cannot be validated, blocking the epic's acceptance criteria.
Mitigation & Contingency
Mitigation: Implement Xledger and Dynamics adapters first (better-documented, sandbox available). Create a mock adapter for Cornerstone/Consio using recorded API responses for CI testing. Proactively request sandbox access from NHF at project kickoff.
Contingency: Ship the epic with Cornerstone/Consio adapters in a 'stub' state (connectivity test returns a simulated success, invoke() is not production-wired) and gate the NHF integration behind a feature flag until real API access is obtained.
Real-world field mappings may include nested transformations, conditional logic, and data type coercions (e.g., Norwegian date formats, currency rounding rules) that the Field Mapping Resolver's initial design does not accommodate, requiring scope expansion mid-epic.
Mitigation & Contingency
Mitigation: Gather actual field mapping examples from Blindeforbundet (Xledger) and HLF (Dynamics) before designing the resolver. Identify the most complex transformation required and ensure the resolver design handles it. Limit Phase 1 to direct field renaming and format conversion only.
Contingency: If complex transformations are required, implement a simple expression evaluator (e.g., JSONata or a custom mini-DSL) as an extension point in the resolver, delivering basic mappings first and complex ones in a follow-up task.