# Next-gen Beacon notification API (subset: real-time SSE notification stream).
# Paths under Pulse DispatcherServlet /MYWORK/service/beacon/v1/...
openapi: 3.0.3
info:
  title: TM Next-Gen — Beacon
  description: |
    OpenAPI for the Beacon real-time notification stream (`beacon/v1/...`).

    Same server base URL as MyWork, task execution, and legacy specs: `/MYWORK/service/`.

    **Authentication:** All endpoints require the `X-reflexis-csrf-token-X` header.

    **Transport:** `GET /beacon/v1/notifications` is a persistent Server-Sent Events (SSE)
    stream, not a single request/response call. The server validates the session, resolves
    `unitId` and `domainNo` from that session (not from query parameters), opens the connection
    to the upstream Beacon microservice, and proxies its `heartbeat`/`RSP`/`WALK` events back to
    the caller unchanged.
    Once the stream is open (HTTP 200, `Content-Type: text/event-stream`), errors are no longer
    expressed as JSON envelopes — the connection is simply closed and the client is expected to
    reconnect.

    Companion specs: `mywork/next-gen-mywork-api.yaml` (application config, broadcasts, notes,
    recent tabs), `task-execution/next-gen-task-execution-api.yaml` (remaining task execution
    endpoints), `walk-execution/next-gen-walk-execution-api.yaml` (walk execution).
  version: 1.0.0
  contact:
    name: API Support
    email: noreply@zebra.com

servers:
  - url: /MYWORK/service/
    description: Application context + Pulse servlet (typical deployment)
  - url: https://fs3.reflexisinc.com/MYWORK/service/
    description: Example development host
  - url: http://localhost:8080/MYWORK/service/
    description: Local Tomcat — app running directly on localhost:8080
  - url: http://localhost:3001/MYWORK/service/
    description: Local CORS proxy — npm run cors-proxy; path must include /MYWORK/service/

tags:
  - name: BeaconNotifications
    description: Real-time SSE notification stream proxied from the external Beacon microservice

security:
  - AuthTokenHeader: []

components:
  securitySchemes:
    AuthTokenHeader:
      type: apiKey
      in: header
      name: X-reflexis-csrf-token-X
      description: Session authentication token validated server-side against the user session store.

  schemas:
    JsonObject:
      type: object
      additionalProperties: true
      description: JSON object (structure varies by endpoint).
    JsonResponse:
      type: object
      additionalProperties: true
      description: Typical wrapper with status/response keys (snake_case in many payloads).
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ER]
          description: Always "ER" for error responses
        errorCode:
          type: string
          description: Application-level error code (e.g. E204, E112, E902)
        response:
          type: string
          description: Human-readable error message
      required: [status, errorCode, response]
      example:
        status: ER
        errorCode: E204
        response: Invalid or expired token
    SseMessage:
      type: object
      description: |
        JSON payload carried in the `data:` field of `RSP`/`WALK` named SSE events. The client
        only reacts to `function`'s presence; additional properties may be present and are not
        required to be consumed.
      required: [function]
      properties:
        function:
          type: string
          enum:
            - FEED
            - RRCMESSAGE
            - BROADCASTMESSAGE
            - WALKSCHEDULEINFO
            - MODELSTATELISTING
            - MODELSTATELISTING_FORM_TEMPLATE
            - MODELSTATELISTING_FORM_INSTANCE
            - FORMMODEL
            - FORMMODEL_TEMPLATE
          description: Discriminator identifying which domain change occurred.
      additionalProperties: true

  responses:
    Unauthorized:
      description: Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            errorCode: E204
            response: Invalid or expired token
    MissingAuthHeader:
      description: X-reflexis-csrf-token-X header is missing (HTTP 400)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            errorCode: E112
            response: X-reflexis-csrf-token-X header is mandatory
    BadRequest:
      description: Invalid or missing request parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Requested unitId/domainNo does not match the authenticated session (HTTP 403)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            errorCode: E902
            response: Requested unitId/domainNo does not match the authenticated session
    InternalServerError:
      description: Unexpected server-side error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: ER
            errorCode: E903
            response: Beacon notification service is unavailable

paths:
  # ---------------------------------------------------------------------------
  # Beacon — real-time notification stream (/beacon/v1/notifications)
  # ---------------------------------------------------------------------------
  /beacon/v1/notifications:
    get:
      tags: [BeaconNotifications]
      summary: Subscribe to the Beacon real-time notification stream
      operationId: subscribeNotifications
      description: |
        Opens a long-lived Server-Sent Events connection that streams `heartbeat`, `RSP`, and
        `WALK` named events for the authenticated user's unit/domain. The response contains
        notification events filtered by the user's domain and unit context.

        **Authentication:** `domainId`, `userId`, `unitId`, `langCode`, and upstream `domainNo`
        are resolved from the validated session (`unitId` ← session unit, `domainNo` ←
        `String.valueOf(session.domainId)`), matching the Angular SSE client. Query parameters
        are not accepted for unit/domain scope.

        ---

        ## Named Events

        | Event | Description |
        |---|---|
        | `heartbeat` | Liveness ping. No meaningful data payload; only resets the client's watchdog timer. |
        | `RSP` | MyWork/feed domain event. `data` is a JSON object matching `SseMessage`. |
        | `WALK` | SWA walk/form domain event. `data` is a JSON object matching `SseMessage`. |

        ## `function` Values

        | SSE Event | `function` | Domain Area |
        |---|---|---|
        | `RSP` | `FEED` | Feed/task list update |
        | `RSP` | `RRCMESSAGE` | Comments/message thread update |
        | `RSP` | `BROADCASTMESSAGE` | Broadcast message update |
        | `WALK` | `WALKSCHEDULEINFO` | Walk schedule/conduct update |
        | `WALK` | `MODELSTATELISTING` | Walk model-state update |
        | `WALK` | `MODELSTATELISTING_FORM_TEMPLATE` | Form template model-state update |
        | `WALK` | `MODELSTATELISTING_FORM_INSTANCE` | Form instance model-state update |
        | `WALK` | `FORMMODEL` | Form instance update |
        | `WALK` | `FORMMODEL_TEMPLATE` | Form template update |

        ---

        ## Error Scenarios

        | Scenario | HTTP | Error Code | Message |
        |---|---|---|---|
        | Missing `X-reflexis-csrf-token-X` header | 400 | `E112` | `X-reflexis-csrf-token-X header is mandatory` |
        | Invalid or expired token | 401 | `E204` | `Invalid or expired token` |
        | Session has no unit id | 400 | `E900` | `unitId is mandatory` |
        | Upstream Beacon forbids unit/domain | 403 | `E902` | `Requested unitId/domainNo does not match the authenticated session` |
        | Upstream Beacon service rejects the forwarded token | 401 | `E204` | `Invalid or expired token` |
        | Upstream Beacon service unavailable or handshake failed | 500 | `E903` | `Beacon notification service is unavailable` |

        ## Error Codes Reference

        | Code | Description |
        |---|---|
        | `E112` | X-reflexis-csrf-token-X header is mandatory |
        | `E204` | Invalid or expired token |
        | `E900` | Session unit id is missing (`unitId` is mandatory) |
        | `E902` | Upstream rejected unit/domain context |
        | `E903` | Beacon notification service is unavailable |
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            enum: [text/event-stream]
          description: Must be `text/event-stream`.
      responses:
        '200':
          description: |
            Success — a `text/event-stream` connection kept open indefinitely. Named events:
            `heartbeat` (no payload), `RSP`/`WALK` (data is a JSON object matching `SseMessage`).
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseMessage'
        '400':
          description: "E112 header missing / E900 session unitId mandatory"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: ER
                errorCode: E900
                response: unitId is mandatory
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
