@defra/grants-reporting-publisher 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @defra/grants-reporting-publisher
 
+## 0.1.2
+
+### Patch Changes
+
+- 62e9659: Make some option fields optional
+
+## 0.1.1
+
+### Patch Changes
+
+- f8be355: Update readme with examples
+
 ## 0.1.0
 
 ### Minor Changes

package/EXAMPLES.md

@@ -0,0 +1,127 @@
+# Usage Examples
+
+This page provides examples of how to use the `@defra/grants-reporting-publisher` library to publish reporting events.
+
+## Configuration
+
+To publish events, you need to provide a configuration object that includes an AWS SNS client and the target topic ARN.
+
+```javascript
+import { SNSClient } from "@aws-sdk/client-sns";
+import {
+  publishReportingEvent,
+  AGREEMENT_CREATED,
+  AGREEMENT_STATUS_CHANGED,
+} from "@defra/grants-reporting-publisher";
+
+const snsClient = new SNSClient({ region: "eu-west-2" });
+
+const config = {
+  snsClient,
+  sns: {
+    topicArn: "arn:aws:sns:eu-west-2:123456789012:your-topic-name",
+  },
+  application: "YOUR_APPLICATION_CODE", // e.g., "GAS or grants-payments-service"
+  service: "your-service-name", // optional, defaults to "grants", just omit this for now
+  generateCorrelationId: true, // automatically generate a UUID for each event
+};
+```
+
+## Event Types
+
+### Agreement Created (`AGREEMENT_CREATED`)
+
+Use this event type when a new agreement is created.
+
+```javascript
+const agreementCreatedEvent = {
+  eventData: {
+    eventType: AGREEMENT_CREATED,
+    agreementId: "AG-123456",
+    agreementType: "WOODLAND",
+    agreementStatus: "ACCEPTED",
+    agreementStartDate: "2026-01-01",
+    agreementEndDate: "2031-12-31",
+    agreementValue: 50000.0,
+    sbi: "200000001",
+    options: [
+      {
+        parcelReference: "SD8545-9935",
+        parcelSizeUnderAgreement: 10.5,
+        optionCode: "WD1",
+        optionYear: 1,
+        optionStartDate: "2026-01-01",
+        optionEndDate: "2026-12-31",
+        optionQuantity: 10.5,
+        optionValue: 10500.0,
+      },
+    ],
+  },
+};
+
+try {
+  const { messageId } = await publishReportingEvent(
+    agreementCreatedEvent,
+    config,
+  );
+  console.log(`Event published with Message ID: ${messageId}`);
+} catch (error) {
+  console.error("Failed to publish event:", error.message);
+}
+```
+
+### Agreement Status Changed (`AGREEMENT_STATUS_CHANGED`)
+
+Use this event type when the status of an existing agreement changes.
+
+```javascript
+const statusChangedEvent = {
+  eventData: {
+    eventType: AGREEMENT_STATUS_CHANGED,
+    agreementId: "AG-123456",
+    agreementStatus: "COMPLETED",
+    statusDate: new Date().toISOString(),
+    agreementStartDate: "2026-01-01",
+    agreementEndDate: "2031-12-31",
+    agreementValue: 50000.0,
+    userId: "user-uuid-123", // optional
+  },
+};
+
+try {
+  const { messageId } = await publishReportingEvent(statusChangedEvent, config);
+  console.log(`Event published with Message ID: ${messageId}`);
+} catch (error) {
+  console.error("Failed to publish event:", error.message);
+}
+```
+
+## Validation Only
+
+If you only want to validate an event without publishing it:
+
+```javascript
+import { validateReportingEvent } from "@defra/grants-reporting-publisher";
+
+const event = {
+  correlationId: "your-correlation-id",
+  datetime: new Date().toISOString(),
+  version: "1.0.0",
+  application: "FCP",
+  service: "grants",
+  eventData: {
+    eventType: AGREEMENT_STATUS_CHANGED,
+    agreementId: "AG-123",
+    agreementStatus: "ACTIVE",
+    statusDate: new Date().toISOString(),
+  },
+};
+
+const { valid, errors, value } = validateReportingEvent(event);
+
+if (!valid) {
+  console.error("Validation errors:", errors);
+} else {
+  console.log("Event is valid:", value);
+}
+```

package/README.md

@@ -4,6 +4,8 @@ NPM module for providing validation and publishing capability for grants reporti
 
 ## Usage
 
+Refer to the [Usage Examples](EXAMPLES.md) for detailed examples of how to publish reporting events.
+
 ### Installation
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/grants-reporting-publisher",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "NPM module for publishing grants reporting events",
   "engines": {
     "node": ">=24",

package/src/publish.test.js

@@ -1,5 +1,5 @@
 import { publishReportingEvent } from "./publish.js";
-import { AGREEMENT_STATUS_CHANGED } from "./constants.js";
+import { AGREEMENT_CREATED, AGREEMENT_STATUS_CHANGED } from "./constants.js";
 
 const mockSend = vi.hoisted(() =>
   vi.fn().mockResolvedValue({ MessageId: "msg-001" }),
@@ -162,6 +162,38 @@ describe("publishAuditEvent", () => {
       await publishReportingEvent(validEvent, baseConfig);
       expect(mockSend).toHaveBeenCalledTimes(1);
     });
+
+    test("publishes AGREEMENT_CREATED event with minimal options", async () => {
+      const agreementCreatedEvent = {
+        correlationId: "abc-123",
+        datetime: "2025-12-01T12:51:41.381Z",
+        version: "1.0.0",
+        application: "FCP001",
+        service: "grants",
+        eventData: {
+          eventType: AGREEMENT_CREATED,
+          agreementId: "WMP123456789",
+          agreementType: "WOODLAND",
+          agreementStatus: "ACCEPTED",
+          sbi: "200000001",
+          options: [
+            {
+              parcelReference: "SD8545-9935",
+              optionCode: "WMP1",
+              optionQuantity: 15.75,
+              optionValue: 1575.0,
+            },
+          ],
+        },
+      };
+
+      const result = await publishReportingEvent(
+        agreementCreatedEvent,
+        baseConfig,
+      );
+      expect(result).toEqual({ messageId: "msg-001" });
+      expect(mockSend).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe("event validation", () => {

package/src/schema.js

@@ -35,8 +35,8 @@ export const eventSchema = Joi.object({
               parcelSizeUnderAgreement: Joi.number().optional(),
               optionCode: Joi.string().required(),
               optionYear: Joi.number().integer().optional(),
-              optionStartDate: Joi.date().iso().required(),
-              optionEndDate: Joi.date().iso().required(),
+              optionStartDate: Joi.date().iso().optional(),
+              optionEndDate: Joi.date().iso().optional(),
               optionQuantity: Joi.number().required(),
               optionValue: Joi.number().required(),
             }),

package/src/validate.test.js

@@ -187,6 +187,28 @@ describe("validateReportingEvent", () => {
     });
 
     test("accepts Agreement created event with minimal options", () => {
+      const result = validateReportingEvent({
+        ...validBase,
+        eventData: {
+          eventType: AGREEMENT_CREATED,
+          agreementId: "WMP123456789",
+          agreementType: "WOODLAND",
+          agreementStatus: "ACCEPTED",
+          sbi: "200000001",
+          options: [
+            {
+              parcelReference: "SD8545-9935",
+              optionCode: "WMP1",
+              optionQuantity: 15.75,
+              optionValue: 1575.0,
+            },
+          ],
+        },
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    test("accepts Agreement created event with option containing optionStartDate only", () => {
       const result = validateReportingEvent({
         ...validBase,
         eventData: {
@@ -200,6 +222,28 @@ describe("validateReportingEvent", () => {
               parcelReference: "SD8545-9935",
               optionCode: "WMP1",
               optionStartDate: "2026-09-01",
+              optionQuantity: 15.75,
+              optionValue: 1575.0,
+            },
+          ],
+        },
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    test("accepts Agreement created event with option containing optionEndDate only", () => {
+      const result = validateReportingEvent({
+        ...validBase,
+        eventData: {
+          eventType: AGREEMENT_CREATED,
+          agreementId: "WMP123456789",
+          agreementType: "WOODLAND",
+          agreementStatus: "ACCEPTED",
+          sbi: "200000001",
+          options: [
+            {
+              parcelReference: "SD8545-9935",
+              optionCode: "WMP1",
               optionEndDate: "2029-08-31",
               optionQuantity: 15.75,
               optionValue: 1575.0,
@@ -210,6 +254,58 @@ describe("validateReportingEvent", () => {
       expect(result.valid).toBe(true);
     });
 
+    test("rejects Agreement created event if optionStartDate is not a valid date", () => {
+      const result = validateReportingEvent({
+        ...validBase,
+        eventData: {
+          eventType: AGREEMENT_CREATED,
+          agreementId: "WMP123456789",
+          agreementType: "WOODLAND",
+          agreementStatus: "ACCEPTED",
+          sbi: "200000001",
+          options: [
+            {
+              parcelReference: "SD8545-9935",
+              optionCode: "WMP1",
+              optionStartDate: "invalid-date",
+              optionQuantity: 15.75,
+              optionValue: 1575.0,
+            },
+          ],
+        },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        '"eventData.options[0].optionStartDate" must be in ISO 8601 date format',
+      );
+    });
+
+    test("rejects Agreement created event if optionEndDate is not a valid date", () => {
+      const result = validateReportingEvent({
+        ...validBase,
+        eventData: {
+          eventType: AGREEMENT_CREATED,
+          agreementId: "WMP123456789",
+          agreementType: "WOODLAND",
+          agreementStatus: "ACCEPTED",
+          sbi: "200000001",
+          options: [
+            {
+              parcelReference: "SD8545-9935",
+              optionCode: "WMP1",
+              optionEndDate: "invalid-date",
+              optionQuantity: 15.75,
+              optionValue: 1575.0,
+            },
+          ],
+        },
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        '"eventData.options[0].optionEndDate" must be in ISO 8601 date format',
+      );
+    });
+
     test("rejects Agreement created event if required fields are missing", () => {
       const result = validateReportingEvent({
         ...validBase,