feat(instances): document calendar event linking

openapi/components/paths/instances.yaml

@@ -87,8 +87,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/instances/InstanceResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "404":
@@ -110,10 +110,40 @@
         - {}
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/instances/InstanceResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
+    put:
+      operationId: updateInstance
+      summary: Update Instance
+      description: |-
+        Set or remove the calendar event linked to a group instance.
+
+        Updating a group instance requires both the `group-instance-manage` and `group-instance-calendar-link` permissions.
+
+        The event must begin within the next six hours or have ended within the previous six hours.
+      tags:
+        - instances
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: ../requests/UpdateInstanceRequest.yaml
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/instances/InstanceResponse.yaml
+        "400":
+          $ref: ../responses/instances/InstanceUpdateValidationError.yaml
+        "401":
+          $ref: ../responses/MissingCredentialsError.yaml
+        "403":
+          $ref: ../responses/instances/InstanceUpdateForbiddenError.yaml
+        "404":
+          $ref: ../responses/instances/InstanceUpdateNotFoundError.yaml
     delete:
       operationId: closeInstance
       summary: Close Instance
@@ -141,8 +171,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/instances/InstanceResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "403":

openapi/components/requests/UpdateInstanceRequest.yaml

@@ -0,0 +1,9 @@
+title: UpdateInstanceRequest
+type: object
+properties:
+  calendarEntryId:
+    type: string
+    description: Calendar event to link to the instance. Send null to remove the current link.
+    nullable: true
+required:
+  - calendarEntryId

openapi/components/responses/instances/InstanceUpdateForbiddenError.yaml

@@ -0,0 +1,16 @@
+description: Error response when the caller lacks permission to manage the instance or its calendar link
+content:
+  application/json:
+    examples:
+      Missing Calendar Link Permission Example:
+        value:
+          error:
+            message: You're not allowed to create or change an instance linked to an event․
+            status_code: 403
+      Missing Instance Management Permission Example:
+        value:
+          error:
+            message: "You're not allowed to edit this instance․"
+            status_code: 403
+    schema:
+      $ref: ../../schemas/Error.yaml

openapi/components/responses/instances/InstanceUpdateNotFoundError.yaml

@@ -0,0 +1,18 @@
+description: >-
+  Error response when the instance does not exist or the requested calendar
+  event belongs to another group
+content:
+  application/json:
+    examples:
+      Event From Another Group Example:
+        value:
+          error:
+            message: Event not found․
+            status_code: 404
+      Instance Not Found Example:
+        value:
+          error:
+            message: Instance not found․
+            status_code: 404
+    schema:
+      $ref: ../../schemas/Error.yaml

openapi/components/responses/instances/InstanceUpdateValidationError.yaml

@@ -0,0 +1,16 @@
+description: Error response when an instance's calendar event link cannot be updated
+content:
+  application/json:
+    examples:
+      Event Outside Link Window Example:
+        value:
+          error:
+            message: You can only link instances to events starting within 6 hours‚ or that have ended within the last 6 hours․
+            status_code: 400
+      Non-Group Instance Example:
+        value:
+          error:
+            message: "'calendarEntryId' is only allowed for group instances․"
+            status_code: 400
+    schema:
+      $ref: ../../schemas/Error.yaml