feat: implement contract event processing tests with tests and docs

[ExcelDsigN-tech]

Implement Contract event processing tests (Closes #88)

Overview

This PR implements a robust contract event processing pipeline for the TalentTrust backend. It establishes explicit semantics for event ingestion, deterministic deduplication, and persistence, validated by a comprehensive suite of unit and integration tests. The implementation prioritizes a modular architecture, enabling testable dependency injection and strict adherence to security and performance standards.

Feature Summary

• Event Ingestion Pipeline: New REST endpoints (POST /api/v1/contracts/events) to receive and normalize inbound contract events.
• Deterministic Deduplication: Logic to identify and reject replayed events using unique idempotency keys, ensuring "exactly-once" processing semantics.
• Modular Persistence: Repository abstraction for event storage, currently featuring an in-memory implementation for high-speed testing and validation.
• Automated Quality Gates: Enforced Jest coverage thresholds (>95%) and ESLint flat config integration to maintain code health.
• Contract Discovery: API support to retrieve unique contract IDs derived from processed event logs.

Technical Implementation

The pipeline follows a Validate -> Dedupe -> Persist orchestration pattern defined in processor.ts.

1. Validation: validation.ts enforces strict ingress schema checks to reject malformed payloads early.
2. Deduplication: dedupe.ts generates identity hashes to provide replay resilience.
3. Persistence: repository.ts abstracts the storage layer, allowing the orchestration service to remain agnostic of the underlying database.
   The application wiring in app.ts was refactored to support dependency injection, facilitating easier integration testing without side effects.

Test Coverage

• Summary: Achieved 98.59% Statement coverage and 96.29% Branch coverage, exceeding the 95% project threshold.
• Suites: 5 dedicated test suites (processor, validation, dedupe, repository, health) consisting of 20+ integration and unit tests.
• Scenarios: Verified 202 Accepted (New), 200 OK (Duplicate), and 400 Bad Request (Malformed) HTTP semantics.

Checklists

• Create feature/backend-38-contract-event-processing-tests branch
• Implement core logic: Ingestion, Deduplication, and Persistence
• Refactor app.ts for DI-based event orchestration
• Achieve >95% test coverage across all new modules
• Add contract-event-processing.md documentation and security notes
• Validate build, lint, and tests pass in local CI-equivalent environment

---

[drips-wave]

@ExcelDsigN-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits