// Copyright (c) VirtuScore Authors 2022. All Rights Reserved.

syntax = "proto3";
option go_package = "github.com/virtuscore/virtuscore/api/results";

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
    info: {
        title: "VirtuScore Results API Service";
        version: "1.0";
        contact: {
            name: "VirtuScore Results API Service";
            url: "https://vs-res.scoreit.nl";
            email: "support@scoreit.nl";
        };
    };
    host : "results.bas.scoring-engine.com";
    schemes: HTTPS;
    consumes: "application/json";
    produces: "application/json";
};

// VirtuScore Results API Service
package virtuscore.api.v1.results;

import "google/type/date.proto";
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";
import "protoc-gen-swagger/options/annotations.proto";
import "validate/validate.proto";

// Results service listens for incoming results queries from the virtual run
// results front-end.
service Results {
    // EventSeriesByMetaEventSeries method receives a meta_event_series_id and returns the event_series details.
    rpc EventSeriesByMetaEventSeries(EventSeriesByMetaEventSeriesRequest) returns (EventSeriesResponse) {
        option (google.api.http) = {
            get: "/v1/meta_event_series/{meta_event_series_id}/event_series"
        };
    }

    // MetaEventsByMetaEventSeries method receives a meta_event_series_id and returns a list of meta_event details.
    rpc MetaEventsByMetaEventSeries(MetaEventsByMetaEventSeriesRequest) returns (MetaEventsResponse) {
        option (google.api.http) = {
            get: "/v1/meta_event_series/{meta_event_series_id}/meta_events"
        };
    }

    // EventsByEventSeries method receives an event_series_id and returns the Events.
    rpc EventsByEventSeries(EventsByEventSeriesRequest) returns (EventsResponse) {
        option (google.api.http) = {
            get: "/v1/event_series/{event_series_id}/events"
        };
    }

    // EventsByMetaEvent method receives a meta_event_id and returns the Events.
    rpc EventsByMetaEvent(EventsByMetaEventRequest) returns (EventsResponse) {
        option (google.api.http) = {
            get: "/v1/meta_events/{meta_event_id}/events"
        };
    }

    // EventConfigsByEventSeries method receives an event_series_id and returns the Event Configs.
    rpc EventConfigs(EventConfigsRequest) returns (EventConfigsResponse) {
        option (google.api.http) = {
            get: "/v1/event_configs/{event_series_id}"
        };
    }

    // EventResults method receives an event_series_id and returns event results.
    rpc EventResults(EventResultsRequest) returns (EventResultsResponse) {
        option (google.api.http) = {
            get: "/v1/event_results/{event_series_id}"
        };
    }

    // CompanyResults method receives an event_series_id and returns company results over the events in the series.
    // Can be passed in various filter/search parameters
    rpc CompanyResults(CompanyResultsRequest) returns (CompanyResultsResponse) {
        option (google.api.http) = {
            get: "/v1/company_results/{event_series_id}"
        };
    }

    // CompanyIndividualResults method receives a company id and returns company departmental results for some company.
    // Can be passed in various filter/search parameters
    rpc CompanyIndividualResults(CompanyIndividualResultsRequest) returns (CompanyIndividualResultsResponse) {
        option (google.api.http) = {
            get: "/v1/company_individual/{event_series_id}/{company_id}"
            additional_bindings {
                get: "/v1/company_individual/{event_series_id}/{company_id}/{entrant_id}"
            }
        };
    }

    // CompanyDepartmentResults method receives a company id and returns company departmental results for some company.
    // Can be passed in various filter/search parameters
    rpc CompanyDepartmentResults(CompanyDepartmentResultsRequest) returns (CompanyDepartmentResultsResponse) {
        option (google.api.http) = {
            get: "/v1/company_department/{event_series_id}/{company_id}"
        };
    }

    // IndividualResults method returns results for all entrants.
    // Can be passed in various filter/search parameters
    rpc IndividualResults(IndividualResultsRequest) returns (IndividualResultsResponse) {
        option (google.api.http) = {
            get: "/v1/individual_results/{event_series_id}"
            additional_bindings {
                get: "/v1/individual_results/{event_series_id}/{entrant_id}"
            }
        };
    }

    // HeatmapResults method returns the most recent runs from each city.
    // Can ask for any number of most recent runs
    rpc HeatmapResults(HeatmapResultsRequest) returns (HeatmapResultsResponse) {
        option (google.api.http) = {
            get: "/v1/heatmap_results/{event_series_id}"
        };
    }

    // TeamResults method returns all the teams across some series.
    // Filterable
    rpc TeamResults(TeamResultsRequest) returns (TeamResultsResponse) {
        option (google.api.http) = {
            get: "/v1/team_results/{event_series_id}"
            additional_bindings {
                get: "/v1/team_results/{event_series_id}/{team_id}"
            },
            additional_bindings {
                get: "/v1/team_results/{event_series_id}/{team_id}/{entrant_id}"
            }
        };
    }

    // TickerStats method returns a bunch of stats for some series.
    rpc TickerStats(TickerStatsRequest) returns (TickerStatsResponse) {
        option (google.api.http) = {
            get: "/v1/ticker_stats/{event_series_id}"
        };
    }
}

// DivisionUnit
enum DivisionUnit {
    // Male
    M = 0;
    // Female
    F = 1;
    // Athletes with Disabilities
    AWD = 2;
}

// CompanySize
enum CompanySize {
    XXS = 0;
    XS = 1;
    SMALL = 2;
    MEDIUM = 3;
    LARGE = 4;
    XL = 5;
    XXL = 6;
}

// EventSeriesByMetaEventSeriesRequest
//
// Request to an EventSeriesByMetaEventSeries call.
message EventSeriesByMetaEventSeriesRequest {
    uint32 meta_event_series_id = 1;
}

// EventSeriesResponse
//
// Response to an EventSeries call.
message EventSeriesResponse {
    // EventSeries
    message EventSeries {
        uint32 id = 1;
        uint32 meta_event_series_id = 2;
        string name = 3;
        google.type.Date begin_date = 5;
        google.type.Date end_date = 6;
    }
    // list of EventSeries
    repeated EventSeries event_series = 1;
}

// MetaEventsByMetaEventSeriesRequest
//
// Request to a MetaEventsByMetaEventSeriesRequest call.
message MetaEventsByMetaEventSeriesRequest {
    uint32 meta_event_series_id = 1;
}

// MetaEventsResponse
//
// Response to a MetaEvents call.
message MetaEventsResponse {
    // MetaEvent
    message MetaEvent {
        uint32 id = 1;
        uint32 meta_event_series_id = 2;
        string city = 3;
        string country = 4;
        string name = 5;
        string timezone = 6;
    }
    // list of MetaEvents
    repeated MetaEvent meta_events = 1;
}

// EventsByEventSeriesRequest
//
// Request to an EventsBySeriesRequest call.
message EventsByEventSeriesRequest {
    uint32 event_series_id = 1;
    bool is_virtual = 2;
}

// EventsByMetaEventRequest
//
// Request to an EventsByMetaEvent call.
message EventsByMetaEventRequest {
    uint32 meta_event_id = 1;
    bool is_virtual = 2;
}

// EventsResponse
//
// List of Events returned from an EventsByEventSeries or EventsByMetaEvent call.
message EventsResponse {
    // Event
    message Event {
        uint32 id = 1;
        uint32 meta_event_id = 2;
        uint32 event_series_id = 3;
        string city = 4;
        string country = 5;
        google.type.Date begin_date = 6;
        google.type.Date end_date = 7;
    }
    // list of Events
    repeated Event events = 1;
}

// EventConfigsRequest
//
// Request to an EventConfigs call.
message EventConfigsRequest {
    uint32 event_series_id = 1;
    uint32 meta_event_id = 2;
}

// EventConfigsResponse
//
// List of Events Configs returned from an EventConfigs or EventsByEventSeries or EventsByMetaEvent call.
message EventConfigsResponse {
    // show this series publicly
    bool show_series_publicly = 1;
    bool show_social_sharing_links = 2;

    // EventConfig
    message EventConfig {
        uint32 id = 1;
        uint32 meta_event_id = 2;
        uint32 event_series_id = 3;
        string city = 4;
        bool is_virtual = 5;
        bool show_results = 6;
        bool show_team_results = 7;
        string default_lang = 8;
        string default_distance_type = 9;
        google.type.Date begin_date = 10;
        google.type.Date end_date = 11;
        bool is_official = 12;
        string jpm_url = 13;
        bool show_non_binary = 14;
    }
    repeated EventConfig event_configs = 3;
}

// EventResultsRequest
//
// Request to EventResults call.
message EventResultsRequest {

    // what series ranking will be retrieved; what's up doc?
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];

    // the ids of events/cities
    repeated uint32 event_ids = 2;

    // controls for sorting and pagination. only sorting makes sense for this call.
    Controls controls = 3;
    // Virtual?
    bool is_virtual = 4;
}

// EventResultsResponse
//
// Holds the response to the EventResults call.
message EventResultsResponse {
    // EventResult
    message EventResult {
        // An event's rank by average time.
        uint32 rank_by_time = 1;
        // An event's rank by total distance.
        uint32 rank_by_distance = 2;
        // The name of the event/city
        string event_city = 3;
        // Number of companies registered for some city.
        uint32 total_teams = 4;
        // Number of entrants registered for some city.
        uint32 total_participants = 5;
        // The average finish time for event/city in a human readable format
        double ave_finish_time = 6;
        // Total Distance in Miles for some city.
        double total_distance_miles = 7;
        // Total Distance in KMs for some city.
        double total_distance_kms = 8;
        // id of event/city
        uint32 event_id = 9;
    }
    // Event results across series.
    repeated EventResult event_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// CompanyResultsRequest
//
// Request to the CompanyResults call.
message CompanyResultsRequest {

    // what event series company results will be retrieved?
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];

    // name of a company
    string company_name = 2;

    // industry name
    string industry = 3;

    // which size company?
    // values expected:
    //    4-9
    //    10-24
    //    25-49
    //    50-99
    //    100-249
    //    250-499
    //    500+
    repeated string company_size = 4;

    // the ids of events/cities
    repeated uint32 event_ids = 5;

    // controls for sorting and pagination
    Controls controls = 6;
    // Virtual
    bool is_virtual = 7;
}

// CompanyResultsResponse
//
// Holds the repsonse to the CompanyResults call.
message CompanyResultsResponse {
    // CompanyResult
    message CompanyResult {
        // An event's rank by average time.
        uint32 global_rank_by_time = 1;
        // An event's rank by total distance.
        uint32 global_rank_by_distance = 2;
        // An event's rank by total distance.
        uint32 city_rank_by_time = 3;
        // An event's rank by total distance.
        uint32 city_rank_by_distance = 4;
        // The name of the event/city
        string event_city = 5;
        // Event id
        uint32 event_id = 6;
        // Name of company
        string company_name = 7;
        // company id
        uint32 company_id = 8;
        // Number of entrant participations for some company.
        uint32 total_participations = 9;
        // The average best finish time for company in a human readable format
        double ave_finish_time = 10;
        // The industry of the company
        string industry = 11;
        // The size of the company
        string company_size = 12;
        // Total Distance in Miles for some company.
        double total_distance_miles = 13;
        // Total Distance in KMs for some company.
        double total_distance_kms = 14;
        // Number of entrant participations for some company.
        uint32 total_participants = 15;
    }
    // Company results across series.
    repeated CompanyResult company_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// CompanyDepartmentResultsRequest
//
// Request to the CompanyDepartmentResults call.
message CompanyDepartmentResultsRequest {

    // the id of the series
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];

    // the id of the company
    uint32 company_id = 2 [(validate.rules).uint32.gt = 0];

    // department to filter on
    string department = 3;

    // controls for sorting and pagination
    Controls controls = 4;
    // Virtual
    bool is_virtual = 5;

}

// CompanyDepartmentResultsResponse
//
// Holds the response to the CompanyDepartmentResults call.
message CompanyDepartmentResultsResponse {
    // CompanyDepartmentResult
    message CompanyDepartmentResult {
        // A department's rank by average time.
        uint32 rank_by_time = 1;
        // An department's rank by total distance.
        uint32 rank_by_distance = 2;
        // Name of Co.
        string company_name = 3;
        // City
        string city_name = 4;
        // The name of the department
        string department = 5;
        // Num participants within the department
        uint32 total_participants = 6;
        // The average best finish time for department in a human readable format
        double ave_finish_time = 7;
        // Total Distance in Miles for some department.
        double total_distance_miles = 8;
        // Total Distance in KMs for some department.
        double total_distance_kms = 9;
    }
    // All company departments.
    repeated CompanyDepartmentResult company_department_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// CompanyIndividualResultsRequest
//
// Request to the CompanyIndividualResults call.
message CompanyIndividualResultsRequest {
    // the id of the series
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];
    // the id of the company
    uint32 company_id = 2 [(validate.rules).uint32.gt = 0];
    // department to filter on
    string department = 3;
    // entrant name
    string participant_name = 4;
    // Lists of genders/AWD
    repeated uint32 gender = 5;
    repeated string awd = 6;
    // controls for sorting and pagination
    bool is_virtual = 7;
    uint32 entrant_id = 8;
    Controls controls = 9;

}

// CompanyIndividualResultsResponse
//
// Holds the response to the CompanyIndividualResults call.
message CompanyIndividualResultsResponse {
    // CompanyIndividualResult
    message CompanyIndividualResult {
        // An entrants's rank by average time.
        uint32 rank_by_time = 1;
        // An entrants's rank by total distance.
        uint32 rank_by_distance = 2;
        // A entrants's dept rank by average time.
        uint32 rank_by_dept_time = 3;
        // An entrants's dept rank by total distance.
        uint32 rank_by_dept_distance = 4;
        // A entrants's gender rank by average time.
        uint32 rank_by_gender_time = 5;
        // An entrants's gender rank by total distance.
        uint32 rank_by_gender_distance = 6;
        // The display name of the person
        string display_name = 7;
        // Name of Co.
        string company_name = 8;
        // City
        string city_name = 9;
        // the department
        string department = 10;
        // entrant's gender (M/F)
        string gender = 11;
        // The best finish time for entrant in a human readable format
        double best_finish_time = 12;
        // Total Distance in Miles for some department.
        double total_distance_miles = 13;
        // Total Distance in KMs for some department.
        double total_distance_kms = 14;
        // AWD for an entrant
        string awd = 15;
        // A entrants's gender rank by average time.
        uint32 rank_by_awd_time = 16;
        // An entrants's gender rank by total distance.
        uint32 rank_by_awd_distance = 17;
        string bib_number = 28;
    }
    // All entrants on company.
    repeated CompanyIndividualResult company_individual_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// IndividualResultsRequest
//
// Request to the IndividualResults call.
message IndividualResultsRequest {
    // the id of the series
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];
    string company_name = 2;
    string participant_name = 3;
    // Name of industry
    string industry = 4;
    // Lists of genders/AWD
    repeated uint32 gender = 5;
    repeated string awd = 6;
    repeated uint32 event_ids = 7;
    bool is_virtual = 8;
    uint32 entrant_id = 9;
    // controls for sorting and pagination
    Controls controls = 10;
}

// CompanyIndividualResultsResponse
//
// Holds the response to the CompanyIndividualResults call.
message IndividualResultsResponse {
    // CompanyIndividualResult
    message IndividualResult {
        // An entrants's rank by average time.
        uint32 global_rank_by_time = 1;
        // A entrants's dept rank by awd.
        uint32 global_rank_by_awd = 2;
        // An entrants's dept rank by awd within city.
        uint32 rank_by_location_awd = 3;
        // A entrants's div rank by industry.
        uint32 global_rank_by_industry = 4;
        // An entrants's div rank by industry within city.
        uint32 rank_by_location_industry = 5;
        // The name of the entrant
        string display_name = 6;
        // entrant's gender (M/F)
        string gender = 7;
        // Name of company
        string company_name = 8;
        // City
        string event_location = 9;
        string industry = 10;
        // Entrant's best time.
        double best_finish_time = 11;
        // AWD for an entrant
        string awd = 12;
        // id of the event
        uint32 event_id = 13;
        // A entrants's dept rank by awd.
        uint32 global_rank_by_gender = 14;
        // An entrants's dept rank by awd within city.
        uint32 rank_by_location_gender = 15;
        // company_id needed to link to individual's company
        uint32 company_id = 16;
        string external_id = 17;
        // holds the unique participant id of the entrant across all events (if available).
        uint32 entrant_id = 18;
        string bib_number = 19;
    }
    // All entrants on company.
    repeated IndividualResult individual_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// HeatmapResultsRequest
//
// Request to HeatmapResults call.
message HeatmapResultsRequest {

    // what event series to use
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];

    // how many runs per city do you want, ordered by finish timestamp (most recent first)
    uint32 num_runs = 2 [(validate.rules).uint32.gt = 0];
}

// HeatmapResultsResponse
//
// Holds the response to the HeatmapResults call.
message HeatmapResultsResponse {
    // HeatmapResult
    message HeatmapResult {
        // An entrant's name.
        string display_name = 1;
        // The company of the entrant.
        string team_name = 2;
        // The name of the event/city
        string event_city = 3;
        // Datestamp of finish time.
        string finish_time = 4;
        // Time of run in seconds.
        uint32 run_time = 5;
        // Latitude at finish.
        double finish_lat = 6;
        // Longitude at finish.
        double finish_long = 7;
    }
    // Event results across series.
    repeated HeatmapResult heatmap_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// TeamResultsRequest
//
// Request to TeamResults call.
message TeamResultsRequest {

    // what event series to use
    uint32 event_series_id = 1 [(validate.rules).uint32.gt = 0];

    repeated uint32 event_ids = 2;
    // Name of company
    string company_name = 3;
    // Name of participant
    string participant_name = 4;
    // Name of industry
    string industry = 5;
    // which divisions to request.
    string division = 6;
    uint32 team_id = 7;
    uint32 entrant_id = 8;
    bool is_virtual = 9;

    // controls for sorting and pagination
    Controls controls = 10;

}

// TeamResultsResponse
//
// Holds the response to the TeamResults call.
message TeamResultsResponse {
    // TeamResult
    message TeamResult {
        // An team's rank by total time.
        uint32 global_rank_by_time = 1;
        // An team's rank by total distance.
        uint32 location_rank_by_time = 2;
        // the company of some team; likely repeated
        string team_name = 3;
        // City
        string event_location = 4;
        // the division (really gender)
        string division = 5;
        // The total time for 4 entrants in seconds
        double total_time = 6;
        // List of entrants on team
        string entrants_info = 7;
        // id of event/city
        uint32 event_id = 8;
        // id of event/city
        uint32 company_id = 9;
        string industry = 10;
        // id of team EPHEMERAL - CHANGES FREQUENTLY B/C TEAMS ARE CONTINUOUSLY RECALCULATED FREQUENTLY
        uint32 team_id = 11;
        // average time of the 4 finishers on this team
        uint32 average_time = 12;
    }
    // All teams in series (filtered).
    repeated TeamResult team_results = 1;
    // response metadata
    Metadata metadata = 2;
}

// TickerStatsRequest
//
// Request to a TickerStats call.
message TickerStatsRequest {
    uint32 event_series_id = 1;
}

// TickerStatsResponse
//
// Response to an TickerStats call.
message TickerStatsResponse {
    // TickerStat
    message TickerStat {
        uint32 cum_miles_run = 1;
        uint32 cum_kms_run = 2;
        string global_ave_pace_in_miles = 3;
        string global_ave_pace_in_kms = 4;
        double ave_finish_time = 5;
        uint32 total_runs_completed = 6;
        uint32 total_finishers = 7;
        uint32 daily_finishers = 8;
        double ran_around_the_globe = 9;
        uint32 total_companies = 10;
        uint32 total_cities = 11;
        uint32 total_countries = 12;
        uint32 total_continents = 13;
    }
    // list of TickerStats
    repeated TickerStat ticker_stats = 1;
}

// Controls
//
// This object allows you to control which part of the resultset should be
// returned and how it should be sorted.
message Controls {
    // page to retrieve for the resultset.
    uint32 page = 1;

    // maximum items per page to return.
    uint32 items_per_page = 2;

    // name of column to sort on.
    string sort_column = 3;

    // SortDirection
    enum SortDirection {
        // use the column's default sort direction.
        DEFAULT = 0;
        // sort column in ascending order.
        ASC = 1;
        // sort column in descending order.
        DESC = 2;
    }
    SortDirection sort_direction = 4 [
        (grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
            description: "sort direction to use."}
    ];
}

// Metadata
//
// This object holds information about the resultset that returned these results.
message Metadata {
    // the amount of items retrieved by the query.
    uint32 total_items = 1;

    // the total amount of records of the query without pagination
    uint32 total_records = 2;

    // the maximum amount of items sent over per page.
    uint32 max_items_per_page = 3;

    // the current page number of the returned items.
    uint32 current_page = 4;

    // the total number of pages available for the query.
    uint32 total_pages = 5;

    // the number of the column sorted on.
    string sort_column = 6;

    // signals if the sort order is reversed (descending).
    bool descending_order = 7;

    // the title of the resultset, if applicable.
    string title = 8;

    // the description / subtitle of the resultset, if applicable.
    string description = 9;

    // whether the results are from a virtual or in-person event
    bool is_virtual = 10;

    // timestamp holding the moment the resultset was compiled.
    google.protobuf.Timestamp queried_at = 11;
}
