Prepare fields for recording more metadata about Gift Aid claim outcomes

Readme.md

@@ -6,3 +6,16 @@ communication.
 Currently it enables us, without hacks, to use Symfony Messenger to publish Donation
 messages from [MatchBot](https://github.com/thebiggive/matchbot) and then consume
 them with [ClaimBot](https://github.com/thebiggive/matchbot).
+
+## Changelog
+
+### v2.0.0
+
+v2 comes alongside a new assumption about what it means for donations to be sent back
+to MatchBot by ClaimBot – this no longer implies an error. Instead status information
+is sent back regardless of outcome and so it is important to have a new field to
+capture the fundamentals about the status.
+
+Although no fields are removed, because of the large downstream change in usage, this
+update came with a new major version to reduce the risk of confusion between the two
+approaches.

src/Donation.php

@@ -19,4 +19,20 @@ class Donation
     public bool $sponsored = false;
     public string $org_hmrc_ref;
     public string $org_name;
+
+    /**
+     * @var string|null From HMRC acknowledgement. Used for subsequent polling status checks and HMRC contact.
+     */
+    public ?string $submissionCorrelationId = null;
+
+    /**
+     * @var bool|null  A minimal status flag: null when claim outcome is not yet determined, false for any
+     *                  kind of error and true for success.
+     */
+    public ?bool $responseSuccess = null;
+
+    /**
+     * @var string|null Once provided, finalised errors or "messages" value from HMRC.
+     */
+    public ?string $responseDetail = null;
 }