namespace team_log

import async
import team
import team_common
import users_common

###############################
# Routes declarations
###############################

struct GetTeamEventsArg
    limit UInt32(min_value=1, max_value=1000) = 1000
        "Number of results to return per call."
    account_id users_common.AccountId?
        "Filter the events by account ID. Return ony events with this account_id as either
        Actor, Context, or Participants."
    time team_common.TimeRange?
        "Filter by time range."
    # category filtering is disablled for now. to be enabled when
    # TeamEventGetEvents.SUPPORT_CATEGORY_BASED_FILTERING_FLAG is changed
    # category EventCategory?
    #    "Filter the returned events to a single category."

    example default
        limit=50
        #category=groups


struct GetTeamEventsResult
    events List(TeamEvent)
        "List of events."
    cursor String
        "Pass the cursor into :route:`get_events/continue` to obtain additional events."
    has_more Boolean
        "Is true if there are additional events that have not been returned yet.
        An additional call to :route:`get_events/continue` can retrieve them."

    example default
        events = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = false

union GetTeamEventsError
    "Errors that can be raised when calling :route:`get_events`."

    account_id_not_found
        "No user found matching the provided account_id."
    invalid_time_range
        "Invalid time range."

    example default
        account_id_not_found = null

route get_events(GetTeamEventsArg, GetTeamEventsResult, GetTeamEventsError)
    "Retrieves team events.

    Permission : Team Auditing."

    attrs
        auth = "team"
        owner = "adminx"
        is_preview = true

struct GetTeamEventsContinueArg
    cursor String
        "Indicates from what point to get the next set of events."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"


union GetTeamEventsContinueError
    "Errors that can be raised when calling :route:`get_events/continue`."

    bad_cursor
        "Bad cursor."

    example default
        bad_cursor = null

route get_events/continue(GetTeamEventsContinueArg, GetTeamEventsResult, GetTeamEventsContinueError)
    "Once a cursor has been retrieved from :route:`get_events`, use this to paginate through all events.

    Permission : Team Auditing."

    attrs
        auth = "team"
        owner = "adminx"
        is_preview = true