docs: document Phase 3 schedule endpoint, model, and resolved open items

openapi.yaml

@@ -245,13 +245,16 @@ paths:
         pairing.
 
         Returns every Block with its start/end times and the ordered list of
-        selected Proclamation IDs. Overnight blocks (an end clock time before
-        the start) are supported and flagged with `overnight: true` and a
-        wrapping `durationMinutes`. Each block also carries `dynamicAudio`;
-        when true, the kiosk enables dynamic audio for the block's duration,
-        overriding any audio selections made on the device. Proclamation
-        content is not included; the kiosk fetches it separately via
-        `/api/v2/proclamations`.
+        selected Proclamation IDs (the legacy daily flattening in `blocks`), and
+        is extended additively with `version`, `type`, `daily`, and `weekly`.
+        Overnight blocks (an end clock time before the start) are supported and
+        flagged with `overnight: true` and a wrapping `durationMinutes`. Each
+        block also carries `dynamicAudio`; when true, the kiosk enables dynamic
+        audio for the block's duration, overriding any audio selections made on
+        the device. Proclamation content is not included; the kiosk fetches it
+        separately via `/api/v2/proclamations`. For `type: "weekly"`, `blocks` is
+        an empty array (the server cannot flatten weekly in the kiosk's
+        timezone). This endpoint emits no ETag and never returns 304.
       operationId: getSchedule
       parameters:
         - in: query
@@ -309,6 +312,66 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorMessage'
+  /api/v2/licenses/{licenseKey}/schedule:
+    get:
+      tags: [Schedule]
+      summary: Get a License Key's schedule (Kiosk-facing, conditional)
+      description: |
+        Kiosk-facing, License-Key-only schedule read. Returns the target payload
+        (`version`, `type`, `daily`, `weekly`, `blocks`). `version` is a
+        content-derived opaque string and is also the `ETag`; a matching
+        `If-None-Match` returns `304`. An unknown License Key is `404`; a key
+        with no Schedule returns `type: null` with empty lists. No
+        authentication (see the API description) beyond the 10/min/IP limit.
+      operationId: getLicenseSchedule
+      parameters:
+        - in: path
+          name: licenseKey
+          required: true
+          schema:
+            type: string
+            pattern: '^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+        - in: header
+          name: If-None-Match
+          required: false
+          schema:
+            type: string
+          description: Prior ETag; when it matches, returns 304.
+      responses:
+        '200':
+          description: The target schedule payload.
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: The quoted `version`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SchedulePayload'
+        '304':
+          description: Not modified; the caller keeps its cached payload.
+          headers:
+            ETag:
+              schema:
+                type: string
+        '404':
+          description: 'Unknown license (`unknown_license`).'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
+        '429':
+          description: Rate limit exceeded (10 requests per minute per IP).
+          headers:
+            Retry-After:
+              schema:
+                type: integer
+                description: Seconds to wait before retrying.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorMessage'
   /api/v2/licenses/{licenseKey}/system-name:
     put:
       tags: [License]
@@ -661,9 +724,51 @@ components:
         email:
           type: string
           format: email
+        version:
+          type: string
+        type:
+          type: string
+          nullable: true
+          enum: [daily, weekly, null]
+        daily:
+          type: array
+          items:
+            $ref: '#/components/schemas/ScheduleBlock'
+        weekly:
+          type: object
+          additionalProperties:
+            type: array
+            items:
+              $ref: '#/components/schemas/ScheduleBlock'
         blocks:
           type: array
-          maxItems: 4
+          items:
+            $ref: '#/components/schemas/ScheduleBlock'
+    SchedulePayload:
+      type: object
+      required: [version, type, daily, weekly, blocks]
+      properties:
+        version:
+          type: string
+          description: Opaque content hash; doubles as the ETag.
+        type:
+          type: string
+          nullable: true
+          enum: [daily, weekly, null]
+        daily:
+          type: array
+          items:
+            $ref: '#/components/schemas/ScheduleBlock'
+        weekly:
+          type: object
+          description: Present with all seven keys when `type` is weekly.
+          additionalProperties:
+            type: array
+            items:
+              $ref: '#/components/schemas/ScheduleBlock'
+        blocks:
+          type: array
+          description: Legacy daily flattening; empty for weekly.
           items:
             $ref: '#/components/schemas/ScheduleBlock'
     OnboardingRequest: