Feature: Implement MuterenBedrijfspercelen (Crop Field Mutation) Flow

[SvenVw]

Description

To support the full data exchange lifecycle with RVO EDI-Crop, we need to implement the mutation flow. This allows users to not only read but also create, update, and terminate crop field registrations.

The mutation process is a multi-step asynchronous flow involving several RVO services.

Objectives

• Implement the MuterenBedrijfspercelen request (CRPRQBM).
• Support polling for processing status via OpvragenProcesvoortgang.
• Support retrieval of validation results and proposed geometry changes via OpvragenValidatieresultaat.
• Implement the formalization (commitment) flow using OphalenTanVolgnummer and FormaliserenOpgave.
• Provide a way to cancel pending requests via AnnulerenOpgave.
• Automate the transformation of GeoJSON (WGS84) to RVO-compatible GML (RD New).
• Allow users to supply raw GML (RD New) directly if they perform their own transformations.

RVO Flow Overview

1. Submit: MuterenBedrijfspercelen -> returns TicketID.
2. Poll: OpvragenProcesvoortgang(TicketID) -> wait for status GEVALIDEERD (Validation complete) or terminal error.
3. Validate: OpvragenValidatieresultaat(TicketID) -> check for FATAAL or FOUT messages.
4. Authorize: OphalenTanVolgnummer() -> returns SequenceNumber.
5. Commit: FormaliserenOpgave(TicketID, SequenceNumber, TanCode).

Proposed Implementation Tasks

1. Type Definitions (src/types.ts)

• Define MutationAction ('I', 'U', 'D').
• Create CropFieldMutation interface (properties + geometry OR gml).
• Create request/response interfaces for all involved services (Muteren, Status, Validation, TAN, Transaction).
• Implement RvoProcessStatusCode union type with all codes from Bijlage D (e.g., GEVALIDEERD, GEPUBLICEERD).

2. SOAP Builders (src/soap/builder.ts)

• Implement buildMuterenRequest with support for Field and CropField nesting.
• Implement logic to choose between gml (raw) and geometry (convert).
• Implement builders for Status, Validation, TAN, Formalize, and Cancel requests.
• Ensure correct SOAP Action codes (CRPRQBM, CRPRQPV, CRPRQFB, CRPRQOT, CRPRQAN).

3. Geometry Utilities (src/utils/geometry.ts)

• Implement transformCoordinatesToRD (WGS84 to EPSG:28992).
• Implement convertGeoJSONToGML to generate RVO-compliant XML snippets for Polygons and MultiPolygons.

4. Response Transformers (src/transformers/mutation.ts)

• Create a dedicated transformer layer to map raw XML objects to clean TypeScript interfaces.
• Handle TicketID and SequenceNumber extraction.
• Map validation result codes and messages.

5. Client Methods (src/client.ts)

• muterenBedrijfspercelen(options)
• opvragenProcesvoortgang(ticketId)
• opvragenValidatieresultaat(ticketId)
• ophalenTanVolgnummer(farmId?)
• formaliserenOpgave(ticketId, sequenceNumber, tanCode)
• annulerenOpgave(ticketId)

6. Verification & Documentation

• Unit tests for GML conversion.
• Unit tests for all new SOAP builders (including raw GML option).
• Unit tests for mutation response transformers.
• Interactive CLI example (examples/mutate-bedrijfspercelen-tvs.ts).
• Update README with mutation flow instructions.

Technical Notes

• Namespaces: Ensure each request uses the appropriate RVO namespace (e.g., http://www.minez.nl/ws/edicrop/1.0/MuterenBedrijfspercelen).
• Cause Codes: Map Insert/Update to 'A' (Active) and Delete to 'D' (Delete) within the CropFieldCause tag (Request). Note that the Validation Response uses different numeric codes (ChangeTypeCode).
• RD New: Coordinates in the GML must be transformed to EPSG:28992 and formatted with exactly 4 decimals (e.g., 155000.1234 463000.5678) to meet the 0.1mm precision requirement.