asyncapi: '2.4.0'
info:
  title: TethysDash Async Notifications
  version: '4.10.2'
  description: |
    With this service client applications get notified about various events
    in the TethysDash system including LRAUV vehicle events, cell connection status,
    as well as about TrackingDB asset positions
    (which are monitored and reported by the
    [odss2dash](https://okeanids.mbari.org/odss2dash/apidoc/) service).

servers:
  okeanids:
    url: okeanids.mbari.org/ws/{token}
    protocol: wss
    description: |
      TethysDash production server.

      Once the socket is open the client will start receiving notifications.

    variables:
      token:
        description: Authentication token.

  tethystest:
    url: tethystest.shore.mbari.org/ws/{token}
    protocol: ws
    description: |
      TethysDash test server.

      Once the socket is open the client will start receiving notifications.

    variables:
      token:
        description: Authentication token.

defaultContentType: application/json

channels:
  /:
    description: The main channel.
    publish:
      summary: Inform of vehicle event.
      operationId: eventGenerated
      message:
        oneOf:
          - $ref: '#/components/messages/event'
          - $ref: '#/components/messages/xevent'


components:
  messages:
    event:
      name: event
      title: LRAUV event has been generated
      summary: Inform about LRAUV event
      contentType: application/json
      payload:
        $ref: "#/components/schemas/Event"

    xevent:
      name: xevent
      title: An X-Event has been generated
      summary: Inform about TrackingDB asset position
      contentType: application/json
      payload:
        $ref: "#/components/schemas/XEvent"

    heartbeat:
      summary: Message to keep the connection alive.
      payload:
        type: string
        enum: ["\r\n"]

  schemas:
    Fix:
      type: object
      properties:
        latitude:
          type: number
        longitude:
          type: number

    EventType:
      type: string
      enum:
        - argoReceive
        - command
        - dataProcessed
        - deploy
        - emergency
        - gpsFix
        - launch
        - logCritical
        - logFault
        - logImportant
        - logPath
        - note
        - patch
        - recover
        - run
        - sbdReceipt
        - sbdReceive
        - sbdSend
        - tracking

    Event:
      type: object
      description: |
        There are different [event types](https://docs.mbari.org/tethysdash/td/eventtypes/)
        in the system, which are captured in a common model.
        While some properties
        (including **eventType**, **vehicleName**, **unixTime**, **isoTime**)
        are relevant to all event types, others will be present in a response depending
        on the concrete type (given by the value of the **eventType** property).

      properties:
        eventId:
          type: integer
          description: Event ID (as captured in the database)
        eventType:
          type: string
          description: Type of the event
          $ref: "#/components/schemas/EventType"
        vehicleName:
          type: string
          description: Name of associated vehicle
        unixTime:
          type: integer
          description: Time of the event
        isoTime:
          type: string
          description: Time of the event in ISO format
        fix:
          $ref: "#/components/schemas/Fix"
          description: Associated position for relevant event types
        state:
          type: integer
          description: Associated state, only for relevant event types
        dataLen:
          type: integer
          description: Associated data length, only for relevant event types
        refId:
          type: integer
          description: Associated refId, only for relevant event types
        index:
          type: integer
          description: Associated index, only for relevant event types
        component:
          type: string
          description: Name of associated component

    XEvent:
      type: object
      description: Object notified upon a new TrackingDB position.

      properties:
        appName:
          type: string
          description: Name of the external application that originated the xevent
        payload:
          type: object
          description: Payload as reported from the external application
          properties:
            assetId:
              type: string
              description: Asset ID in the TrackingDB
            assetName:
              type: string
              description: Asset name
            position:
              $ref: "#/components/schemas/XPosition"
              description: Asset position
            typeName:
              type: string
              description: Asset type as captured in the TrackingDB
            color:
              type: string
              description: Asset color as captured in the TrackingDB
            iconUrl:
              type: string
              description: Asset icon URL as captured in the TrackingDB

    XPosition:
      type: object
      description: Asset position

      properties:
        timeMs:
          type: integer
        lat:
          type: number
        lon:
          type: number