ServerStatistics/api/ServerStatistics.api

syntax = "v1"

info (
	title:   "Server Statistics API"
	desc:    "Server Statistics API"
	author:  "cialloo"
	date:    "2025-10-04"
	version: "v1"
)

type (
	PingReq  {}
	PingResp {
		OK bool `json:"ok"`
	}
)

type (
	TotalPlayerJoinReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
	}
	TotalPlayerJoinResp {
		Count int64 `json:"count"`
	}
)

type (
	TotalPlayerCountReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
	}
	TotalPlayerCountResp {
		Count int64 `json:"count"`
	}
)

type (
	TotalPlayTimeReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
	}
	TotalPlayTimeResp {
		TotalPlayTime int64 `json:"totalPlayTime"` // Total playtime in seconds
	}
)

type (
	TotalKillCountReq {
		TimeRangeStart int64    `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64    `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		HeadshotOnly   bool     `json:"headshotOnly"` // If true, count only headshot kills
		WeaponFilter   []string `json:"weaponFilter"` // List of weapon names to filter by (optional)
		PlayerFilter   []string `json:"playerFilter"` // List of player SteamID64s to filter by (optional)
	}
	TotalKillCountResp {
		TotalKillCount int64 `json:"totalKillCount"` // Total kill count
	}
)

type (
	TotalConnectCountReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
	}
	TotalConnectCountResp {
		TotalConnectCount int64 `json:"totalConnectCount"` // Total connect count
	}
)

type (
	TotalDamageCountReq {
		TimeRangeStart int64    `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64    `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		WeaponFilter   []string `json:"weaponFilter"` // List of weapon names to filter by (optional)
		PlayerFilter   []string `json:"playerFilter"` // List of player SteamID64s to filter by (optional)
	}
	TotalDamageCountResp {
		TotalDamageCount int64 `json:"totalDamageCount"` // Total damage count
	}
)

type (
	TotalChatMessageCountReq {
		TimeRangeStart int64    `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64    `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		PlayerFilter   []string `json:"playerFilter"` // List of player SteamID64s to filter by (optional)
	}
	TotalChatMessageCountResp {
		TotalChatMessageCount int64 `json:"totalChatMessageCount"` // Total chat message count
	}
)

type (
	RecentJoinPlayerReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		Limit          int   `json:"limit,range=[1:10],example=10,default=10"` // Maximum number of players to return
	}
	RecentJoinPlayerResp {
		Players []RecentJoinPlayerRespPlayer `json:"players"` // List of player SteamID64s who joined in the time range
	}
	RecentJoinPlayerRespPlayer {
		SteamID64 string `json:"steamID64"` // Player's SteamID64
		JoinTime  int64  `json:"joinTime"` // Join time as Unix timestamp in milliseconds
		UserName  string `json:"userName"` // Player's username at the time of joining
		PlayTime  int64  `json:"playTime"` // Playtime in seconds since joining
	}
)

type (
	RecentChatMessageReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		Limit          int   `json:"limit,range=[1:10],example=10,default=10"` // Maximum number of messages to return
	}
	RecentChatMessageResp {
		Messages []RecentChatMessageRespMessage `json:"messages"` // List of recent chat messages
	}
	RecentChatMessageRespMessage {
		SteamID64  string `json:"steamID64"` // Player's SteamID64
		UserName   string `json:"userName"` // Player's username at the time of message
		Message    string `json:"message"` // Chat message content
		TimeStamp  int64  `json:"timeStamp"` // Message timestamp as Unix timestamp in milliseconds
		ServerName string `json:"serverName"` // Server name where the message was sent
		MapName    string `json:"mapName"` // Map name where the message was sent
		ServerIP   string `json:"serverIP"` // Server IP where the message was sent
		ServerPort int    `json:"serverPort"` // Server port where the message was sent
	}
)

type (
	RecentPlayReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		LeastPlayTime  int64 `json:"leastPlayTime"` // Least playtime in seconds to filter by
		Limit          int   `json:"limit,range=[1:10],example=10,default=10"` // Maximum number of players to return
	}
	RecentPlayResp {
		Players []RecentPlayRespPlayer `json:"players"` // List of players who played in the time range
	}
	RecentPlayRespPlayer {
		SteamID64 string `json:"steamID64"` // Player's SteamID64
		UserName  string `json:"userName"` // Player's username at the time of playing
		MapName   string `json:"mapName"` // Map name where the player played
		PlayTime  int64  `json:"playTime"` // Playtime in seconds during the time range
	}
)

type (
	TopPlayTimeReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		Limit          int   `json:"limit,range=[1:10],example=10,default=10"` // Maximum number of players to return
	}
	TopPlayTimeResp {
		Players []TopPlayTimeRespPlayer `json:"players"` // List of top players by playtime
	}
	TopPlayTimeRespPlayer {
		SteamID64 string `json:"steamID64"` // Player's SteamID64
		UserName  string `json:"userName"` // Player's username at the time of playing
		PlayTime  int64  `json:"playTime"` // Playtime in seconds during the time range
	}
)

type (
	TopKillerReq {
		TimeRangeStart int64 `json:"timeRangeStart"` // Unix timestamp in milliseconds
		TimeRangeEnd   int64 `json:"timeRangeEnd"` // Unix timestamp in milliseconds
		Limit          int   `json:"limit,range=[1:10],example=10,default=10"` // Maximum number of players to return
	}
	TopKillerResp {
		Players []TopKillerRespPlayer `json:"players"` // List of top players by kill count
	}
	TopKillerRespPlayer {
		SteamID64 string `json:"steamID64"` // Player's SteamID64
		UserName  string `json:"userName"` // Player's username at the time of playing
		KillCount int64  `json:"killCount"` // Kill count during the time range
	}
)

type (
	ServerListReq  {}
	ServerListResp {
		ServerName string `json:"serverName"` // Server name
		ServerIP   string `json:"serverIP"` // Server IP address
		ServerPort int    `json:"serverPort"` // Server port
		Category   string `json:"category"` // Server category
		MapName    string `json:"mapName"` // Current map name
		HumanCount int    `json:"humanCount"` // Current human player count
		BotCount   int    `json:"botCount"` // Bot count
	}
)

@server (
	prefix: /api/server/statistics
)
service ServerStatistics {
	@doc (
		summary:     "Ping the server to check if it's alive"
		description: "Ping the server to check if it's alive"
	)
	@handler pingHandler
	get /ping (PingReq) returns (PingResp)

	@doc (
		summary:     "Get recent player joins within a specified time range"
		description: "Get recent player joins within a specified time range"
	)
	@handler recentPlayerJoinHandler
	post /recent-player-join (TotalPlayerJoinReq) returns (TotalPlayerJoinResp)

	@doc (
		summary:     "Get total player count within a specified time range"
		description: "Get total Total count within a specified time range"
	)
	@handler totalPlayerCountHandler
	post /total-player-count (TotalPlayerCountReq) returns (TotalPlayerCountResp)

	@doc (
		summary:     "Get total kill count within a specified time range"
		description: "Get total kill count within a specified time range"
	)
	@handler totalKillCountHandler
	post /total-kill-count (TotalKillCountReq) returns (TotalKillCountResp)

	@doc (
		summary:     "Get total playtime within a specified time range"
		description: "Get total playtime within a specified time range"
	)
	@handler totalPlayTimeHandler
	post /total-play-time (TotalPlayTimeReq) returns (TotalPlayTimeResp)

	@doc (
		summary:     "Get total connect count within a specified time range"
		description: "Get total connect count within a specified time range"
	)
	@handler totalConnectCountHandler
	post /total-connect-count (TotalConnectCountReq) returns (TotalConnectCountResp)

	@doc (
		summary:     "Get total damage count within a specified time range"
		description: "Get total damage count within a specified time range"
	)
	@handler totalDamageCountHandler
	post /total-damage-count (TotalDamageCountReq) returns (TotalDamageCountResp)

	@doc (
		summary:     "Get total chat message count within a specified time range"
		description: "Get total chat message count within a specified time range"
	)
	@handler totalChatMessageCountHandler
	post /total-chat-message-count (TotalChatMessageCountReq) returns (TotalChatMessageCountResp)

	@doc (
		summary:     "Get recent players who joined within a specified time range"
		description: "Get recent players who joined within a specified time range"
	)
	@handler recentJoinPlayerHandler
	post /recent-join-player (RecentJoinPlayerReq) returns (RecentJoinPlayerResp)

	@doc (
		summary:     "Get recent chat messages within a specified time range"
		description: "Get recent chat messages within a specified time range"
	)
	@handler recentChatMessageHandler
	post /recent-chat-message (RecentChatMessageReq) returns (RecentChatMessageResp)

	@doc (
		summary:     "Get recent players who played within a specified time range"
		description: "Get recent players who played within a specified time range"
	)
	@handler recentPlayHandler
	post /recent-play (RecentPlayReq) returns (RecentPlayResp)

	@doc (
		summary:     "Get top players by playtime within a specified time range"
		description: "Get top players by playtime within a specified time range"
	)
	@handler topPlayTimeHandler
	post /top-play-time (TopPlayTimeReq) returns (TopPlayTimeResp)

	@doc (
		summary:     "Get top players by kill count within a specified time range"
		description: "Get top players by kill count within a specified time range"
	)
	@handler topKillerHandler
	post /top-killer (TopKillerReq) returns (TopKillerResp)

	@doc (
		summary:     "Get the list of monitored game servers"
		description: "Get the list of monitored game servers"
	)
	@handler ServerListHandler
	get /list (ServerListReq) returns ([]ServerListResp)
}