feat: support appointments with an operation

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    paths: ['**/*.kt', '**/*.kts', '.github/workflows/ci.yml']
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    name: "Run Tests"
+
+    env:
+      GH_USERNAME: ${{ github.actor }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 23
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: 23
+
+      - name: Cache Gradle dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Test
+        run: ./gradlew test

src/main/kotlin/com/ctrlhub/core/projects/appointments/response/Appointment.kt

@@ -0,0 +1,32 @@
+package com.ctrlhub.core.projects.appointments.response
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.github.jasminb.jsonapi.StringIdHandler
+import com.github.jasminb.jsonapi.annotations.Id
+import com.github.jasminb.jsonapi.annotations.Type
+
+@Type("appointments")
+@JsonIgnoreProperties(ignoreUnknown = true)
+class Appointment @JsonCreator constructor(
+    @Id(StringIdHandler::class) var id: String = "",
+    @JsonProperty("animals") val animals: Boolean = false,
+    @JsonProperty("end_time") val endTime: String = "",
+    @JsonProperty("medical_dependency") val medicalDependency: Boolean = false,
+    @JsonProperty("notes") val notes: String = "",
+    @JsonProperty("on_ecr") val onEcr: Boolean = false,
+    @JsonProperty("on_ecr_notes") val onEcrNotes: String = "",
+    @JsonProperty("start_time") val startTime: String = ""
+) {
+    constructor() : this(
+        id = "",
+        animals = false,
+        endTime = "",
+        medicalDependency = false,
+        notes = "",
+        onEcr = false,
+        onEcrNotes = "",
+        startTime = ""
+    )
+}

src/main/kotlin/com/ctrlhub/core/projects/operations/OperationsRouter.kt

@@ -5,16 +5,18 @@ import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.projects.workorders.WorkOrdersRouter
 import com.ctrlhub.core.projects.operations.response.Operation
 import com.ctrlhub.core.iam.response.User
+import com.ctrlhub.core.projects.appointments.response.Appointment
 import com.ctrlhub.core.projects.operations.templates.response.OperationTemplate
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.FilterOption
 import com.ctrlhub.core.router.request.JsonApiIncludes
-import com.ctrlhub.core.router.request.RequestParameters
 import com.ctrlhub.core.router.request.RequestParametersWithIncludes
 import io.ktor.client.HttpClient
 
 enum class OperationIncludes(val value: String) : JsonApiIncludes {
     Template("template"),
+    Appointments("appointment"),
+    Properties("properties"),
     Forms("forms");
 
     override fun value(): String {
@@ -46,7 +48,7 @@ class OperationsRouter(httpClient: HttpClient) : Router(httpClient) {
 
         return fetchPaginatedJsonApiResources(
             endpoint, requestParameters.toMap(), Operation::class.java,
-            OperationTemplate::class.java, User::class.java
+            OperationTemplate::class.java, User::class.java, Appointment::class.java
         )
     }
 

src/main/kotlin/com/ctrlhub/core/projects/operations/response/Operation.kt

@@ -2,6 +2,7 @@ package com.ctrlhub.core.projects.operations.response
 
 import com.ctrlhub.core.api.Assignable
 import com.ctrlhub.core.geo.Property
+import com.ctrlhub.core.projects.appointments.response.Appointment
 import com.ctrlhub.core.projects.operations.templates.response.OperationTemplate
 import com.ctrlhub.core.projects.response.Label
 import com.fasterxml.jackson.annotation.JsonCreator
@@ -36,6 +37,9 @@ class Operation @JsonCreator constructor(
 
     @Relationship("properties")
     var properties: java.util.List<Property>? = null,
+
+    @Relationship("appointment")
+    var appointment: Appointment? = null
 ) {
     constructor(): this(
         name = "",

src/test/kotlin/com/ctrlhub/core/projects/operations/OperationsRouterTest.kt

@@ -97,4 +97,44 @@ class OperationsRouterTest {
             assertEquals("Example Template Name", response.data[0].template?.name)
         }
     }
+
+    @Test
+    fun `can retrieve all operations with included appointments`() {
+        val jsonFilePath = Paths.get("src/test/resources/projects/operations/all-operations-with-included-appointments.json")
+        val jsonContent = Files.readString(jsonFilePath)
+
+        val mockEngine = MockEngine { request ->
+            respond(
+                content = jsonContent,
+                status = HttpStatusCode.OK,
+                headers = headersOf(HttpHeaders.ContentType, "application/json")
+            )
+        }
+
+        val operationsRouter = OperationsRouter(httpClient = HttpClient(mockEngine).configureForTest())
+
+        runBlocking {
+            val response = operationsRouter.all(
+                organisationId = "123",
+                requestParameters = OperationRequestParameters(
+                    includes = listOf(
+                        OperationIncludes.Appointments
+                    )
+                )
+            )
+
+            assertIs<PaginatedList<Operation>>(response)
+
+            // Find the operation that has an appointment
+            val operationWithAppointment = response.data.find { it.appointment != null }
+            assertNotNull(operationWithAppointment, "Should have at least one operation with an appointment")
+
+            // Validate the appointment is properly hydrated
+            val appointment = operationWithAppointment?.appointment
+            assertNotNull(appointment, "Appointment should not be null")
+            assertEquals("appointment-1", appointment?.id)
+            assertEquals("2025-08-15T07:00:00Z", appointment?.startTime)
+            assertEquals("2025-08-15T11:00:00Z", appointment?.endTime)
+        }
+    }
 }

src/test/resources/projects/operations/all-operations-with-included-appointments.json

@@ -0,0 +1,203 @@
+{
+  "data": [
+    {
+      "id": "operation-1",
+      "type": "operations",
+      "attributes": {
+        "code": "ANON-TK0002",
+        "dates": {
+          "scheduled": {}
+        },
+        "description": "",
+        "labels": [
+          {
+            "key": "Time band",
+            "value": "AM"
+          }
+        ],
+        "name": "Anonymised Task 1",
+        "requirements": {
+          "forms": [
+            {
+              "id": "form-1",
+              "required": true
+            }
+          ]
+        }
+      },
+      "relationships": {
+        "appointment": {
+          "data": null
+        },
+        "assignees": {
+          "data": [
+            { "id": "user-1", "type": "users" },
+            { "id": "user-2", "type": "users" },
+            { "id": "user-3", "type": "users" },
+            { "id": "user-4", "type": "users" }
+          ]
+        },
+        "forms": {
+          "data": [
+            { "id": "form-1", "type": "forms" }
+          ]
+        },
+        "organisation": {
+          "data": { "id": "org-1", "type": "organisations" }
+        },
+        "permits": { "data": [] },
+        "properties": {
+          "data": [
+            { "id": "property-1", "type": "properties" },
+            { "id": "property-2", "type": "properties" },
+            { "id": "property-3", "type": "properties" },
+            { "id": "property-4", "type": "properties" },
+            { "id": "property-5", "type": "properties" },
+            { "id": "property-6", "type": "properties" },
+            { "id": "property-7", "type": "properties" }
+          ]
+        },
+        "scheme": {
+          "data": { "id": "scheme-1", "type": "schemes" }
+        },
+        "streets": { "data": [] },
+        "teams": { "data": [] },
+        "template": { "data": null },
+        "work_order": {
+          "data": { "id": "workorder-1", "type": "work-orders" }
+        }
+      },
+      "meta": {
+        "created_at": "2025-03-13T00:00:00.000Z",
+        "updated_at": "2025-07-16T00:00:00.000Z",
+        "counts": { "properties": 7, "streets": 0 }
+      }
+    },
+    {
+      "id": "operation-2",
+      "type": "operations",
+      "attributes": {
+        "code": "",
+        "dates": {
+          "scheduled": {
+            "start": "2025-08-15T07:00:00Z",
+            "end": "2025-08-15T11:00:00Z"
+          }
+        },
+        "description": "",
+        "labels": [],
+        "name": "Anonymised Operation 2",
+        "requirements": {
+          "forms": [
+            { "id": "form-1", "required": true }
+          ]
+        }
+      },
+      "relationships": {
+        "appointment": {
+          "data": { "id": "appointment-1", "type": "appointments" }
+        },
+        "assignees": {
+          "data": [ { "id": "user-4", "type": "users" } ]
+        },
+        "forms": {
+          "data": [ { "id": "form-1", "type": "forms" } ]
+        },
+        "organisation": {
+          "data": { "id": "org-1", "type": "organisations" }
+        },
+        "permits": { "data": [] },
+        "properties": { "data": [] },
+        "scheme": { "data": { "id": "scheme-2", "type": "schemes" } },
+        "streets": { "data": [] },
+        "teams": { "data": [] },
+        "template": { "data": null },
+        "work_order": { "data": { "id": "workorder-2", "type": "work-orders" } }
+      },
+      "meta": {
+        "created_at": "2025-08-14T00:00:00.000Z",
+        "updated_at": "2025-08-14T00:00:00.000Z",
+        "counts": { "properties": 0, "streets": 0 }
+      }
+    },
+    {
+      "id": "operation-3",
+      "type": "operations",
+      "attributes": {
+        "code": "",
+        "dates": { "scheduled": {} },
+        "description": "",
+        "labels": [],
+        "name": "Anonymised Operation 3",
+        "requirements": {
+          "forms": [ { "id": "form-1", "required": true } ]
+        }
+      },
+      "relationships": {
+        "appointment": { "data": null },
+        "assignees": { "data": [ { "id": "user-4", "type": "users" } ] },
+        "forms": { "data": [ { "id": "form-1", "type": "forms" } ] },
+        "organisation": { "data": { "id": "org-1", "type": "organisations" } },
+        "permits": { "data": [] },
+        "properties": { "data": [] },
+        "scheme": { "data": { "id": "scheme-2", "type": "schemes" } },
+        "streets": { "data": [] },
+        "teams": { "data": [] },
+        "template": { "data": null },
+        "work_order": { "data": { "id": "workorder-2", "type": "work-orders" } }
+      },
+      "meta": {
+        "created_at": "2025-08-14T00:00:00.000Z",
+        "updated_at": "2025-08-14T00:00:00.000Z",
+        "counts": { "properties": 0, "streets": 0 }
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "current_page": 1,
+      "counts": { "resources": 3, "pages": 1 },
+      "requested": { "offset": 0, "limit": 100 },
+      "offsets": { "previous": null, "next": null }
+    },
+    "features": {
+      "params": {
+        "include": {
+          "options": [
+            "appointment", "assignees", "forms", "organisation", "permits", "properties", "scheme", "streets", "teams", "template", "work_order"
+          ]
+        },
+        "sort": { "default": "", "options": null }
+      }
+    }
+  },
+  "jsonapi": { "version": "1.0" },
+  "included": [
+    {
+      "id": "appointment-1",
+      "type": "appointments",
+      "attributes": {
+        "animals": false,
+        "end_time": "2025-08-15T11:00:00Z",
+        "medical_dependency": false,
+        "notes": "",
+        "on_ecr": false,
+        "on_ecr_notes": "",
+        "start_time": "2025-08-15T07:00:00Z"
+      },
+      "relationships": {
+        "author": { "data": { "id": "user-4", "type": "authors" } },
+        "interaction": { "data": { "id": "interaction-1", "type": "customer-interactions" } },
+        "operation": { "data": { "id": "operation-2", "type": "operations" } },
+        "organisation": { "data": { "id": "org-1", "type": "organisations" } },
+        "time_band": { "data": { "id": "timeband-1", "type": "time-bands" } }
+      },
+      "meta": {
+        "created_at": "2025-08-14T00:00:00.000Z",
+        "updated_at": "2025-08-14T00:00:00.000Z",
+        "modified_at": "2025-08-14T00:00:00.000Z"
+      }
+    }
+  ]
+}
+