feat(instances): document calendar event linking

openapi/components/paths/instances.yaml

@@ -28,7 +28,7 @@
           $ref: ../responses/MissingCredentialsError.yaml
   /instances/recent:
     get:
       operationId: getRecentLocations
       summary: List Recent Locations
       description: |-
         Returns a list of recently visited locations.
@@ -61,8 +61,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/instances/InstanceResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "404":
@@ -84,10 +84,28 @@
         - {}
         - 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 an instance.
+      tags:
+        - instances
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: ../requests/UpdateInstanceRequest.yaml
+      security:
+        - authCookie: []
+      responses:
+        "200":
+          $ref: ../responses/instances/InstanceResponse.yaml
+        "400":
+          $ref: ../responses/RequestValidationError.yaml
     delete:
       operationId: closeInstance
       summary: Close Instance
@@ -115,8 +133,8 @@
       security:
         - authCookie: []
       responses:
         "200":
           $ref: ../responses/instances/InstanceResponse.yaml
         "401":
           $ref: ../responses/MissingCredentialsError.yaml
         "403":

openapi/components/requests/UpdateInstanceRequest.yaml

@@ -0,0 +1,7 @@
+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

test/arazzo.yaml

@@ -1338,6 +1338,71 @@ workflows:
         outputs:
           calendarId: $response.body#/id
 
+      - stepId: create-instance
+        x-security:
+          - schemeName: authCookie
+            values:
+              apiKey: $workflows.session.outputs.sessionToken
+        operationId: $sourceDescriptions.default.createInstance
+        requestBody:
+          contentType: application/json
+          payload:
+            worldId: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b
+            type: group
+            region: use
+            ownerId: $steps.create-group.outputs.groupId
+            groupAccessType: members
+        successCriteria:
+          - condition: $statusCode == 200
+        onFailure:
+          - name: stop
+            type: end
+
+        outputs:
+          instanceId: $response.body#/instanceId
+
+      - stepId: link-instance-event
+        x-security:
+          - schemeName: authCookie
+            values:
+              apiKey: $workflows.session.outputs.sessionToken
+        operationId: $sourceDescriptions.default.updateInstance
+        parameters:
+          - name: worldId
+            in: path
+            value: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b
+          - name: instanceId
+            in: path
+            value: $steps.create-instance.outputs.instanceId
+        requestBody:
+          contentType: application/json
+          payload:
+            calendarEntryId: $steps.create-event.outputs.calendarId
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.body#/calendarEntryId == $steps.create-event.outputs.calendarId
+
+      - stepId: unlink-instance-event
+        x-security:
+          - schemeName: authCookie
+            values:
+              apiKey: $workflows.session.outputs.sessionToken
+        operationId: $sourceDescriptions.default.updateInstance
+        parameters:
+          - name: worldId
+            in: path
+            value: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b
+          - name: instanceId
+            in: path
+            value: $steps.create-instance.outputs.instanceId
+        requestBody:
+          contentType: application/json
+          payload:
+            calendarEntryId: null
+        successCriteria:
+          - condition: $statusCode == 200
+          - condition: $response.body#/calendarEntryId == null
+
       - stepId: calendar-events
         x-security:
           - schemeName: authCookie
@@ -1513,6 +1578,22 @@ workflows:
         successCriteria:
           - condition: $statusCode == 404
 
+      - stepId: close-instance
+        x-security:
+          - schemeName: authCookie
+            values:
+              apiKey: $workflows.session.outputs.sessionToken
+        operationId: $sourceDescriptions.default.closeInstance
+        parameters:
+          - name: worldId
+            in: path
+            value: wrld_4cf554b4-430c-4f8f-b53e-1f294eed230b
+          - name: instanceId
+            in: path
+            value: $steps.create-instance.outputs.instanceId
+        successCriteria:
+          - condition: $statusCode == 200
+
       - stepId: delete-group
         x-security:
           - schemeName: authCookie