Add schedule sync and schedule-aware playback

2026-09-11 19:14:55 -05:00
parent a043ec84d8
commit f37beaf07e
23 changed files with 893 additions and 32 deletions
@@ -31,6 +31,8 @@ tags:
    description: Proclamation content, optionally scoped by license entitlement.
  - name: License
    description: License key validation.
+  - name: Schedule
+    description: A user's daily listening schedule, consumed by the kiosk.
  - name: Automations
    description: Signed machine-to-machine webhooks.
 paths:
@@ -230,6 +232,83 @@ paths:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
+  /api/v2/schedule:
+    get:
+      tags: [Schedule]
+      summary: Get a user's listening schedule (query-param auth)
+      description: |
+        Machine-to-app endpoint used by the RadiantWave kiosk. Authenticates via
+        the paired `email` + `licenseKey` **query parameters** and validates only
+        that the key belongs to the account for that email. License
+        active/entitlement is deliberately not checked here: an invalid license
+        would already lock the kiosk out, so this endpoint only checks the
+        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`.
+      operationId: getSchedule
+      parameters:
+        - in: query
+          name: email
+          required: true
+          schema:
+            type: string
+            format: email
+          description: Account email.
+        - in: query
+          name: licenseKey
+          required: true
+          schema:
+            type: string
+            pattern: '^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$'
+          description: License key. The legacy alias `key` is also accepted.
+      responses:
+        '200':
+          description: The user's schedule (possibly empty).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ScheduleResponse'
+              example:
+                email: jane@example.com
+                blocks:
+                  - id: 3f1c2b7a-9d4e-4c8a-b2f6-1a2b3c4d5e6f
+                    startTime: '21:00'
+                    startMinutes: 1260
+                    endTime: '09:00'
+                    endMinutes: 540
+                    overnight: true
+                    durationMinutes: 720
+                    dynamicAudio: true
+                    proclamationIds:
+                      - b40fdcb9-703c-420e-af32-a081964c6f08
+                      - 7c9e1a2b-3d4e-5f60-8a9b-0c1d2e3f4a5b
+        '400':
+          description: |
+            Missing/invalid parameters, unknown key or user, or the key does not
+            belong to the email's account. Possible messages: `not-authorized`,
+            `this key doesn't appear to belong to you`.
+          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/automations/create/account:
    post:
      tags: [Automations]
@@ -436,6 +515,72 @@ components:
        email_address:
          type: string
          format: email
+    ScheduleBlock:
+      type: object
+      required:
+        [
+          id,
+          startTime,
+          startMinutes,
+          endTime,
+          endMinutes,
+          overnight,
+          durationMinutes,
+          dynamicAudio,
+          proclamationIds
+        ]
+      properties:
+        id:
+          type: string
+          format: uuid
+        startTime:
+          type: string
+          example: '06:00'
+          description: Wall-clock start time as `HH:MM`.
+        startMinutes:
+          type: integer
+          minimum: 0
+          maximum: 1440
+          description: Minutes from midnight.
+        endTime:
+          type: string
+          example: '08:00'
+          description: Wall-clock end time as `HH:MM`.
+        endMinutes:
+          type: integer
+          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.
+        dynamicAudio:
+          type: boolean
+          description: |
+            When true, dynamic audio is enabled for the block's duration, overriding any
+            audio selections made on the device while the block is active.
+        proclamationIds:
+          type: array
+          description: IDs of the selected Proclamations, in play order.
+          items:
+            type: string
+            format: uuid
+    ScheduleResponse:
+      type: object
+      required: [email, blocks]
+      properties:
+        email:
+          type: string
+          format: email
+        blocks:
+          type: array
+          maxItems: 4
+          items:
+            $ref: '#/components/schemas/ScheduleBlock'
    OnboardingRequest:
      type: object
      required: [email]