Flag overnight blocks in the v2 schedule API

docs/ai/api.md

@@ -107,8 +107,10 @@ Authenticates with the paired `email` + `licenseKey` query parameters and
 validates only that the key belongs to the account (not that the license is
 active/entitled). Returns the user's Blocks with start/end times and the IDs of
 the selected Proclamations (content is fetched separately via
-`/api/v2/proclamations`). Rate limited to 10 requests per minute per IP.
-Failure messages follow the existing v2 shape:
+`/api/v2/proclamations`). Overnight blocks (end clock time before start) are
+supported and flagged with `overnight: true` plus a wrapping `durationMinutes`.
+Rate limited to 10 requests per minute per IP. Failure messages follow the
+existing v2 shape:
 `not-authorized` or `this key doesn't appear to belong to you`.
 
 ---

docs/openapi.yaml

@@ -245,7 +245,9 @@ paths:
         pairing.
 
         Returns every Block with its start/end times and the ordered list of
-        selected Proclamation IDs. Proclamation content is not included; the
+        selected Proclamation IDs. Overnight blocks (an end clock time before
+        the start) are supported and flagged with `overnight: true` and a
+        wrapping `durationMinutes`. Proclamation content is not included; the
         kiosk fetches it separately via `/api/v2/proclamations`.
       operationId: getSchedule
       parameters:
@@ -498,7 +500,17 @@ components:
           format: email
     ScheduleBlock:
       type: object
-      required: [id, startTime, startMinutes, endTime, endMinutes, proclamationIds]
+      required:
+        [
+          id,
+          startTime,
+          startMinutes,
+          endTime,
+          endMinutes,
+          overnight,
+          durationMinutes,
+          proclamationIds
+        ]
       properties:
         id:
           type: string
@@ -521,6 +533,13 @@ components:
           minimum: 0
           maximum: 1440
           description: Minutes from midnight.
+        overnight:
+          type: boolean
+          description: True when the end clock time is at or before the start, i.e. the block crosses midnight.
+        durationMinutes:
+          type: integer
+          minimum: 1
+          description: Block length in minutes. An overnight block counts the wrap past midnight as the next day.
         proclamationIds:
           type: array
           description: IDs of the selected Proclamations, in play order.