IEC Integration Contracts — Technical Documentation

This document describes the `iec/integration-contracts` package: its purpose, public API, and patterns for implementing Drivers and related services.

Purpose

Provide a stable, framework-agnostic contract for IEC integrations, defining the interfaces and DTOs used between the core IEC system and integration Drivers (e.g., Magento 2). It decouples IEC’s pipeline from specific downstream systems.

Namespaces

• Root: `IEC\IntegrationContracts`
• Key packages:

- `Contracts`: `DriverContract`, `AbstractDriver`, `EntityMappingServiceInterface`, `IntegrationContextInterface`

- `Data`: `MutationData`, `MappingData`

- `Enum`: `EntityTypes`

Data Transfer Objects

• `Data\MutationData`

- Immutable DTO with fields:

- `entity_type: string` — e.g., `product`, `category`, etc.

- `entity_uuid: string` — local entity UUID

- `operation: string` — `created|updated|deleted`

- `payload: array<string,mixed>` — current state after change

- `changed_fields: array<int,string>` — flattened set of changed fields

• `Data\MappingData`

- `externalId: string`

- `externalData: array<string,mixed>|null`

Contracts

• `Contracts\DriverContract`

- Identity: `getName(): string`, `getType(): string`, `getVersion(): string`, `getDescription(): string`

- Capabilities: `getSupportedEntityTypes(): array<string>`

- Processing: `handle(MutationData $mutation)`, `handleBatch(array $mutations)`

- Configuration: `getConfigurationSchema(): array` — Laravel validation rules for driver config

• `Contracts\AbstractDriver` (implements `DriverContract`)

- Provides defaults and holds:

- `public array $supportedEntityTypes` (defaults: product, category, attribute, family)

- `public array $integrationData = []` — populated by IEC when instantiating

- `public LoggerInterface $logger` — default `NullLogger`

- Requires implementation of `getName()`, `getType()`, `getVersion()`, `handle()`, `handleBatch()`, `getConfigurationSchema()`

• `Contracts\EntityMappingServiceInterface`

- `find(string $entityType, string $entityUuid, string $integrationUuid): ?MappingData`

- `create(string $entityType, string $entityUuid, string $integrationUuid, string $externalId, ?array $externalData): void`

• `Contracts\IntegrationContextInterface`

- Context for drivers if needed (e.g., environment, clock, feature flags). Define and bind in the app.

Driver Lifecycle in IEC

1. IEC discovers drivers via container tagging and returns instances from `DriverDiscovery`.

2. An `Integration` is configured with a driver `type` and driver `configuration` which is validated against `getConfigurationSchema()`.

3. When a `MutationJob` runs, IEC instantiates the driver, sets `integrationData` and `logger`, and calls `handle(MutationData)`.

4. Drivers use `EntityMappingServiceInterface` to map local UUIDs to external IDs, deciding create vs update.

Best Practices

• Treat `MutationData` as immutable; avoid mutating and prefer mapping/transform layers.
• Validate configuration strictly; fail fast with clear error messages to enable retries or operator fixes.
• Use `logger` for structured logs; avoid `echo`/`dd` in production.
• Make `handleBatch()` idempotent and order-agnostic if possible; batch by entity type.
• Persist mappings as soon as external entities are created; use robust keys (e.g., SKU).
• Timeouts and retries should respect IEC’s Integration settings; propagate transient errors to allow retries.

Example Driver Skeleton

use IEC\IntegrationContracts\Contracts\AbstractDriver;
use IEC\IntegrationContracts\Data\MutationData;

final class ExampleDriver extends AbstractDriver
{
    public function getName(): string { return 'Example'; }
    public function getType(): string { return 'example'; }
    public function getVersion(): string { return '1.0.0'; }
    public function getDescription(): string { return 'Example integration'; }

    public function handle(MutationData $mutation): void
    {
        $this->logger->info('Handling mutation', [
            'type' => $mutation->entity_type,
            'uuid' => $mutation->entity_uuid,
            'op'   => $mutation->operation,
        ]);
        // lookup mapping, call external API, update mapping, etc.
    }

    public function handleBatch(array $mutations): void
    {
        foreach ($mutations as $m) {
            $this->handle($m);
        }
    }

    public function getConfigurationSchema(): array
    {
        return [
            'base_url' => 'required|url',
            'api_key'  => 'required|string',
        ];
    }
}

Versioning & Compatibility

• Maintain backward compatibility for DTO field names and semantics.
• Introduce new capabilities via optional fields or new interfaces; bump minor/major versions accordingly.

Testing Guidance

• Unit test drivers against mocked `EntityMappingServiceInterface`.
• Use contract tests to exercise `handle()` with typical and edge-case `MutationData` payloads.