module Wire.API.Routes.Public.Galley.TeamNotification where

import Data.Range
import Imports
import Servant
import Wire.API.Error
import Wire.API.Error.Galley
import Wire.API.Notification
import Wire.API.Routes.Named
import Wire.API.Routes.Public

type TeamNotificationAPI =
  Named
    "get-team-notifications"
    ( Summary "Read recently added team members from team queue"
        :> Description GetTeamNotificationsDescription
        :> "teams"
        :> "notifications"
        :> ZUser
        :> CanThrow 'TeamNotFound
        :> CanThrow 'InvalidTeamNotificationId
        :> QueryParam'
             [ Optional,
               Strict,
               Description "Notification id to start with in the response (UUIDv1)"
             ]
             "since"
             NotificationId
        :> QueryParam'
             [ Optional,
               Strict,
               Description "Maximum number of events to return (1..10000; default: 1000)"
             ]
             "size"
             (Range 1 10000 Int32)
        :> Get '[Servant.JSON] QueuedNotificationList
    )

type GetTeamNotificationsDescription =
  "This is a work-around for scalability issues with gundeck user event fan-out. \
  \It does not track all team-wide events, but only `member-join`.\
  \\n\
  \Note that `/teams/notifications` behaves differently from `/notifications`:\
  \\n\
  \- If there is a gap between the notification id requested with `since` and the \
  \available data, team queues respond with 200 and the data that could be found. \
  \They do NOT respond with status 404, but valid data in the body.\
  \\n\
  \- The notification with the id given via `since` is included in the \
  \response if it exists.  You should remove this and only use it to decide whether \
  \there was a gap between your last request and this one.\
  \\n\
  \- If the notification id does *not* exist, you get the more recent events from the queue \
  \(instead of all of them).  This can be done because a notification id is a UUIDv1, which \
  \is essentially a time stamp.\
  \\n\
  \- There is no corresponding `/last` end-point to get only the most recent event. \
  \That end-point was only useful to avoid having to pull the entire queue.  In team \
  \queues, if you have never requested the queue before and \
  \have no prior notification id, just pull with timestamp 'now'."