From 71ffca1c37b846ece37dbd815fc33f1c75a0daa3 Mon Sep 17 00:00:00 2001
From: Evan Strat <5790137+evan10s@users.noreply.github.com>
Date: Sun, 29 Oct 2023 02:30:35 -0400
Subject: [PATCH] feat(frc_events): Add FRC Events as an alternative match data
 source (#60)

Co-authored-by: Evan Strat <evan10s@users.noreply.github.com>
---
 .../components/alerts/FrcEventsWarning.vue    |  25 +++
 client/src/components/alerts/GlobalAlerts.vue |   2 +
 .../components/alerts/NoPlaylistMappings.vue  |   1 +
 .../src/components/alerts/PrivateUploads.vue  |   1 +
 .../components/alerts/SandboxModeAlert.vue    |   1 +
 .../alerts/YouTubeAuthIncompleteAlert.vue     |   1 +
 .../matches/MatchDataAttribution.vue          |  19 ++
 .../src/components/matches/MatchSelector.vue  |  13 +-
 client/src/types/IObfuscatedSecrets.ts        |   1 +
 client/src/types/ISettings.ts                 |   1 +
 client/src/views/Settings.vue                 |  57 +++++-
 server/settings/secrets.example.json          |   3 +-
 server/settings/settings.example.json         |   3 +-
 server/src/models/CompLevel.ts                |  32 +++
 server/src/models/Settings.ts                 |   2 +
 server/src/models/frcEvents/frcScoredMatch.ts | 191 ++++++++++++++++++
 .../frcEvents/frcScoredMatchesResponse.ts     |   5 +
 server/src/models/frcEvents/frcTeam.ts        |   5 +
 .../models/frcEvents/frcTournamentLevel.ts    |   2 +
 .../src/models/theBlueAlliance/tbaAlliance.ts |   2 +-
 server/src/repos/FrcEventsRepo.ts             | 121 +++++++++++
 server/src/routes/matches.ts                  |   8 +-
 server/src/services/MatchesService.ts         |  82 +++++++-
 server/src/services/SettingsService.ts        |   1 +
 24 files changed, 566 insertions(+), 13 deletions(-)
 create mode 100644 client/src/components/alerts/FrcEventsWarning.vue
 create mode 100644 client/src/components/matches/MatchDataAttribution.vue
 create mode 100644 server/src/models/frcEvents/frcScoredMatch.ts
 create mode 100644 server/src/models/frcEvents/frcScoredMatchesResponse.ts
 create mode 100644 server/src/models/frcEvents/frcTeam.ts
 create mode 100644 server/src/models/frcEvents/frcTournamentLevel.ts
 create mode 100644 server/src/repos/FrcEventsRepo.ts

diff --git a/client/src/components/alerts/FrcEventsWarning.vue b/client/src/components/alerts/FrcEventsWarning.vue
new file mode 100644
index 0000000..4c94267
--- /dev/null
+++ b/client/src/components/alerts/FrcEventsWarning.vue
@@ -0,0 +1,25 @@
+<template>
+  <VAlert v-if="!settingsStore.isFirstLoad && settingsStore.settings?.useFrcEventsApi"
+          color="warning"
+          variant="tonal"
+          density="comfortable"
+          :rounded="props.rounded ?? 0"
+          icon="mdi-alert-outline"
+  >
+    <template v-slot:text>
+      <strong>Using FRC Events API.</strong> This is not recommended unless match data is unavailable on The Blue
+      Alliance.
+    </template>
+  </VAlert>
+</template>
+<script lang="ts" setup>
+import {useSettingsStore} from "@/stores/settings";
+
+const settingsStore = useSettingsStore();
+settingsStore.getSettings();
+
+interface IProps {
+  rounded?: number;
+}
+const props = defineProps<IProps>();
+</script>
diff --git a/client/src/components/alerts/GlobalAlerts.vue b/client/src/components/alerts/GlobalAlerts.vue
index b28e244..e9506a7 100644
--- a/client/src/components/alerts/GlobalAlerts.vue
+++ b/client/src/components/alerts/GlobalAlerts.vue
@@ -4,6 +4,7 @@
     <SandboxModeAlert />
     <PrivateUploads />
     <NoPlaylistMappings />
+    <FrcEventsWarning />
   </div>
 </template>
 
@@ -12,4 +13,5 @@ import SandboxModeAlert from "@/components/alerts/SandboxModeAlert.vue";
 import YouTubeAuthIncompleteAlert from "@/components/alerts/YouTubeAuthIncompleteAlert.vue";
 import NoPlaylistMappings from "@/components/alerts/NoPlaylistMappings.vue";
 import PrivateUploads from "@/components/alerts/PrivateUploads.vue";
+import FrcEventsWarning from "@/components/alerts/FrcEventsWarning.vue";
 </script>
diff --git a/client/src/components/alerts/NoPlaylistMappings.vue b/client/src/components/alerts/NoPlaylistMappings.vue
index 687c784..f8d6049 100644
--- a/client/src/components/alerts/NoPlaylistMappings.vue
+++ b/client/src/components/alerts/NoPlaylistMappings.vue
@@ -2,6 +2,7 @@
   <VAlert v-if="!playlistsStore.isFirstLoad && !playlistsStore.playlists?.length"
           color="info"
           variant="tonal"
+          density="comfortable"
           :rounded="props.rounded ?? 0"
           icon="mdi-upload-off"
   >
diff --git a/client/src/components/alerts/PrivateUploads.vue b/client/src/components/alerts/PrivateUploads.vue
index 08c7926..8e861f5 100644
--- a/client/src/components/alerts/PrivateUploads.vue
+++ b/client/src/components/alerts/PrivateUploads.vue
@@ -2,6 +2,7 @@
   <VAlert v-if="!settingsStore.isFirstLoad && settingsStore.settings?.youTubeVideoPrivacy !== 'public'"
           color="warning"
           variant="tonal"
+          density="comfortable"
           :rounded="props.rounded ?? 0"
           icon="mdi-eye-off"
   >
diff --git a/client/src/components/alerts/SandboxModeAlert.vue b/client/src/components/alerts/SandboxModeAlert.vue
index bfc72cc..100ad7b 100644
--- a/client/src/components/alerts/SandboxModeAlert.vue
+++ b/client/src/components/alerts/SandboxModeAlert.vue
@@ -2,6 +2,7 @@
   <VAlert v-if="!settingsStore.isFirstLoad && settingsStore.settings?.sandboxModeEnabled"
           color="warning"
           variant="tonal"
+          density="comfortable"
           :rounded="props.rounded ?? 0"
           icon="mdi-upload-off"
   >
diff --git a/client/src/components/alerts/YouTubeAuthIncompleteAlert.vue b/client/src/components/alerts/YouTubeAuthIncompleteAlert.vue
index 6368438..190cd65 100644
--- a/client/src/components/alerts/YouTubeAuthIncompleteAlert.vue
+++ b/client/src/components/alerts/YouTubeAuthIncompleteAlert.vue
@@ -3,6 +3,7 @@
           color="error"
           variant="tonal"
           :rounded="0"
+          density="comfortable"
           icon="mdi-alert-circle"
   >
     <template v-slot:text>
diff --git a/client/src/components/matches/MatchDataAttribution.vue b/client/src/components/matches/MatchDataAttribution.vue
new file mode 100644
index 0000000..3ea0085
--- /dev/null
+++ b/client/src/components/matches/MatchDataAttribution.vue
@@ -0,0 +1,19 @@
+<template>
+  <p v-if="settingsStore.settings?.useFrcEventsApi"
+     class="text-caption"
+  >
+    <VIcon icon="mdi-information" /> <a target="_blank" href="https://frc-events.firstinspires.org/services/API">
+      Event Data provided by <em>FIRST</em>
+    </a>
+  </p>
+  <p v-else class="text-caption">
+    <VIcon icon="mdi-information" /> <a target="_blank" href="https://thebluealliance.com">
+      Powered by The Blue Alliance
+    </a>
+  </p>
+</template>
+<script lang="ts" setup>
+import {useSettingsStore} from "@/stores/settings";
+
+const settingsStore = useSettingsStore();
+</script>
diff --git a/client/src/components/matches/MatchSelector.vue b/client/src/components/matches/MatchSelector.vue
index cfcf3e1..62af1af 100644
--- a/client/src/components/matches/MatchSelector.vue
+++ b/client/src/components/matches/MatchSelector.vue
@@ -5,6 +5,13 @@
   >
     {{ matchListStore.error }}
   </VAlert>
+
+  <VRow class="mb-1">
+    <VCol>
+      <MatchDataAttribution />
+    </VCol>
+  </VRow>
+
   <!--
   Note: this component may be laggy when running in development, but in production builds the performance
   should become significantly better.
@@ -31,7 +38,7 @@
       >
         Refresh
       </VBtn>
-      <VBtn v-if="matchStore.selectedMatchKey"
+      <VBtn v-if="!settingsStore.settings?.useFrcEventsApi && matchStore.selectedMatchKey"
             prepend-icon="mdi-open-in-new"
             variant="outlined"
             class="ml-2"
@@ -71,9 +78,13 @@
 import {useMatchStore} from "@/stores/match";
 import {useMatchListStore} from "@/stores/matchList";
 import {onMounted} from "vue";
+import FrcEventsWarning from "@/components/alerts/FrcEventsWarning.vue";
+import {useSettingsStore} from "@/stores/settings";
+import MatchDataAttribution from "@/components/matches/MatchDataAttribution.vue";
 
 const matchStore = useMatchStore();
 const matchListStore = useMatchListStore();
+const settingsStore = useSettingsStore();
 
 onMounted(() => {
   matchListStore.getMatchList();
diff --git a/client/src/types/IObfuscatedSecrets.ts b/client/src/types/IObfuscatedSecrets.ts
index f7fff51..5c231af 100644
--- a/client/src/types/IObfuscatedSecrets.ts
+++ b/client/src/types/IObfuscatedSecrets.ts
@@ -5,5 +5,6 @@ export interface IObfuscatedSecrets {
     theBlueAllianceReadApiKey: boolean,
     theBlueAllianceTrustedApiAuthId: boolean,
     theBlueAllianceTrustedApiAuthSecret: boolean,
+    frcEventsApiKey: boolean,
     [key: string]: boolean,
 }
diff --git a/client/src/types/ISettings.ts b/client/src/types/ISettings.ts
index 1c7582e..4b7123c 100644
--- a/client/src/types/ISettings.ts
+++ b/client/src/types/ISettings.ts
@@ -11,6 +11,7 @@ export interface ISettings {
   sandboxModeEnabled: boolean,
   youTubeVideoPrivacy: string,
   linkVideosOnTheBlueAlliance: boolean;
+  useFrcEventsApi: boolean;
   [key: string]: string | boolean,
 }
 
diff --git a/client/src/views/Settings.vue b/client/src/views/Settings.vue
index c066250..03ffb24 100644
--- a/client/src/views/Settings.vue
+++ b/client/src/views/Settings.vue
@@ -89,8 +89,7 @@
                 variant="tonal"
                 class="mt-4 mb-4"
         >
-          Before you can enter your TBA trusted API auth ID and secret, you need to enable this feature using the
-          toggle above.
+          Some settings are hidden because linking match videos on TBA is disabled. Enable the feature to see them.
         </VAlert>
 
         <AutosavingTextInput v-if="
@@ -120,6 +119,50 @@
                                ''"
         />
 
+        <h2 class="mt-4">
+          FRC Events API
+        </h2>
+        <p class="mt-4">
+          If match data is unavailable on The Blue Alliance, it may be available on the FRC Events API. You can check
+          if data is available on
+          <a href="https://frc-events.firstinspires.org/">https://frc-events.firstinspires.org/</a> and request API
+          credentials at
+          <a href="https://frc-events.firstinspires.org/services/API">
+            https://frc-events.firstinspires.org/services/API
+          </a>.
+        </p>
+        <p class="mt-4 mb-2">
+          To compute the API key, base64 encode the text <code>username:AuthorizationKey</code> and then
+          paste it below.
+        </p>
+
+        <p class="mt-4">Retrieve match data from FRC Events</p>
+        <AutosavingBtnSelectGroup :choices="['On', 'Off']"
+                                  :default-value="settingsStore.settings?.useFrcEventsApi ? 'On' : 'Off'"
+                                  :loading="savingFrcEventsApiKey"
+                                  @on-choice-selected="saveFrcEventsApiKey"
+        />
+
+        <VAlert v-if="!settingsStore.settings?.useFrcEventsApi"
+                color="info"
+                variant="tonal"
+                class="mt-4 mb-4"
+        >
+          Some settings are hidden because FRC Events integration is disabled. Enable the feature to see them.
+        </VAlert>
+        <AutosavingTextInput v-else
+                             :key="`frcEventsApiKey-${dataRefreshKey}`"
+                             :on-submit="submit"
+                             initial-value=""
+                             name="frcEventsApiKey"
+                             label="Base64-encoded FRC Events API key"
+                             input-type="password"
+                             setting-type="secret"
+                             :help-text="settingsStore.obfuscatedSecrets?.frcEventsApiKey ?
+                               'Current value hidden' :
+                               ''"
+        />
+
         <h2 class="mt-4">
           Playlist mappings
         </h2>
@@ -301,6 +344,16 @@ const tbaReadApiKeyHelpText = computed((): string => {
   return baseText;
 });
 
+// TODO(Evan): Move into its own component
+const savingFrcEventsApiKey = ref(false);
+
+async function saveFrcEventsApiKey(value: string): Promise<void> {
+  savingFrcEventsApiKey.value = true;
+  await submit("useFrcEventsApi", value === "On", "setting");
+  await refreshData(false);
+  savingFrcEventsApiKey.value = false;
+}
+
 </script>
 
 <style scoped>
diff --git a/server/settings/secrets.example.json b/server/settings/secrets.example.json
index bf7b2b3..e794b62 100644
--- a/server/settings/secrets.example.json
+++ b/server/settings/secrets.example.json
@@ -5,5 +5,6 @@
   "googleTokenExpiry": "",
   "theBlueAllianceReadApiKey": "",
   "theBlueAllianceTrustedApiAuthId": "",
-  "theBlueAllianceTrustedApiAuthSecret": ""
+  "theBlueAllianceTrustedApiAuthSecret": "",
+  "frcEventsApiKey": ""
 }
diff --git a/server/settings/settings.example.json b/server/settings/settings.example.json
index 9aab444..db81861 100644
--- a/server/settings/settings.example.json
+++ b/server/settings/settings.example.json
@@ -7,5 +7,6 @@
   "sandboxModeEnabled": true,
   "playoffsType": "Double elimination playoff",
   "youTubeVideoPrivacy": "private",
-  "linkVideosOnTheBlueAlliance": false
+  "linkVideosOnTheBlueAlliance": false,
+  "useFrcEventsApi": false
 }
diff --git a/server/src/models/CompLevel.ts b/server/src/models/CompLevel.ts
index 5cbb9ba..4fe9cd5 100644
--- a/server/src/models/CompLevel.ts
+++ b/server/src/models/CompLevel.ts
@@ -1,4 +1,6 @@
 /* eslint-disable no-unused-vars */
+import { type FrcApiTournamentLevel } from "@src/models/frcEvents/frcTournamentLevel";
+
 /**
  * Represents the competition level of a match.
  */
@@ -48,3 +50,33 @@ export function abbreviatedCompLevel(compLevel: CompLevel): string {
             throw new Error(`Comp level ${compLevel} is invalid.`);
     }
 }
+
+export function toFrcApiTournamentLevel(compLevel: CompLevel): FrcApiTournamentLevel {
+    switch (compLevel) {
+        case CompLevel.Qualification:
+            return "qual";
+        case CompLevel.Quarterfinal:
+            return "playoff";
+        case CompLevel.Semifinal:
+            return "playoff";
+        case CompLevel.Final:
+            return "playoff";
+        default:
+            throw new Error(`Comp level ${compLevel} is invalid.`);
+    }
+}
+
+export function toFrcEventsUrlTournamentLevel(compLevel: CompLevel): string {
+    switch (compLevel) {
+        case CompLevel.Qualification:
+            return "qualifications";
+        case CompLevel.Quarterfinal:
+            return "playoffs";
+        case CompLevel.Semifinal:
+            return "playoffs";
+        case CompLevel.Final:
+            return "playoffs";
+        default:
+            throw new Error(`Comp level ${compLevel} is invalid.`);
+    }
+}
diff --git a/server/src/models/Settings.ts b/server/src/models/Settings.ts
index 37fa939..1b67190 100644
--- a/server/src/models/Settings.ts
+++ b/server/src/models/Settings.ts
@@ -8,6 +8,7 @@ export interface ISettings {
     sandboxModeEnabled: boolean,
     youTubeVideoPrivacy: string,
     linkVideosOnTheBlueAlliance: boolean;
+    useFrcEventsApi: boolean;
 }
 
 export type SettingsKey = keyof ISettings;
@@ -20,6 +21,7 @@ export interface ISecretSettings {
     theBlueAllianceReadApiKey: string,
     theBlueAllianceTrustedApiAuthId: string,
     theBlueAllianceTrustedApiAuthSecret: string,
+    frcEventsApiKey: string,
     [key: string]: string,
 }
 
diff --git a/server/src/models/frcEvents/frcScoredMatch.ts b/server/src/models/frcEvents/frcScoredMatch.ts
new file mode 100644
index 0000000..bcc4fa1
--- /dev/null
+++ b/server/src/models/frcEvents/frcScoredMatch.ts
@@ -0,0 +1,191 @@
+import { type FrcTeam } from "@src/models/frcEvents/frcTeam";
+import { type TbaMatchSimple } from "@src/models/theBlueAlliance/tbaMatchesSimpleApiResponse";
+import { type TbaWinningAlliance } from "@src/models/theBlueAlliance/tbaWinningAlliance";
+import { type TbaCompLevel } from "@src/models/theBlueAlliance/tbaCompLevel";
+import { CompLevel } from "@src/models/CompLevel";
+
+export interface FrcScoredMatch {
+    tournamentLevel: string;
+    matchNumber: number;
+    scoreRedFinal: number | null | undefined;
+    scoreBlueFinal: number | null | undefined
+    teams: FrcTeam[];
+}
+
+export function isFrcScoredMatch(obj: object): obj is FrcScoredMatch {
+    return !!(obj as FrcScoredMatch).tournamentLevel &&
+        !!(obj as FrcScoredMatch).matchNumber &&
+        !!(obj as FrcScoredMatch).teams;
+}
+
+function convertMatchWinnerToTba(redScore: number | null | undefined,
+                                 blueScore: number | null | undefined): TbaWinningAlliance {
+    if (redScore === null ||
+        blueScore === null ||
+        typeof redScore === "undefined" ||
+        typeof blueScore === "undefined" ||
+        redScore === blueScore
+    ) {
+        return "";
+    }
+    if (redScore > blueScore) {
+        return "red";
+    }
+
+    return "blue";
+}
+
+/**
+ * Coerce tournament level and match number from FRC Events into a TBA competition level.
+ *
+ * NOTE: This function doesn't support Best of 3 currently.
+ * @param tournamentLevel
+ * @param matchNumber
+ */
+function getTbaCompLevel(tournamentLevel: string, matchNumber: number): TbaCompLevel {
+    if (tournamentLevel === "Qualification") {
+        return "qm";
+    }
+
+    // This is assuming double elimination, for simplicity
+    if (tournamentLevel === "Playoff") {
+        if (matchNumber <= 13) {
+            return "sf";
+        }
+
+        return "f";
+    }
+
+    throw new Error(`getTbaCompLevel: Tournament level ${tournamentLevel} is not supported.`);
+}
+
+/**
+ * Coerce tournament level and match number from FRC Events into a TBA set number.
+ *
+ * NOTE: This function doesn't support Best of 3 currently.
+ * @param tournamentLevel
+ * @param matchNumber
+ */
+function getTbaSetNumber(tournamentLevel: string, matchNumber: number): number {
+    if (tournamentLevel === "Qualification") {
+        return 1;
+    }
+
+    // This is assuming double elimination, for simplicity
+    if (tournamentLevel === "Playoff") {
+        // On TBA, matches 1-3 in double elimination are sf#m1
+        if (matchNumber <= 13) {
+            return matchNumber;
+        }
+
+        // Matchs 14+ are finals, which only has 1 set
+        return 1;
+    }
+
+    throw new Error(`getTbaSetNumber: Tournament level ${tournamentLevel} is not supported.`);
+}
+
+/**
+ * Coerce tournament level and match number from FRC Events into a TBA match key.
+ *
+ * NOTE: This function doesn't support Best of 3 currently.
+ * @param match
+ * @param eventKey
+ */
+function getTbaMatchKey(match: FrcScoredMatch, eventKey: string): string {
+    if (match.tournamentLevel === "Qualification") {
+        return `${eventKey}_qm${match.matchNumber}`;
+    }
+
+    if (match.tournamentLevel === "Playoff") {
+        const compLevel = getTbaCompLevel(match.tournamentLevel, match.matchNumber);
+        const setNumber = getTbaSetNumber(match.tournamentLevel, match.matchNumber);
+
+        let actualMatchNumber = match.matchNumber;
+
+        // Handle finals matches, which FRC Events numbers starting at 14 but TBA numbers starting at 1
+        if (match.matchNumber > 13) {
+            actualMatchNumber -= 13;
+        } else {
+            // The double elimination matches for rounds 1-5 have 1-13 as their set number, while the match
+            // number is always one
+            actualMatchNumber = 1;
+        }
+
+        return `${eventKey}_${compLevel}${setNumber}m${actualMatchNumber}`;
+    }
+
+    throw new Error(`getTbaMatchKey: Tournament level ${match.tournamentLevel} is not supported.`);
+}
+
+/**
+ * Coerce tournament level and match number into a TBA match key.
+ * @param year
+ * @param eventCode
+ */
+function getTbaEventKey(year: string, eventCode: string): string {
+    return `${year}${eventCode}`;
+}
+
+/**
+ * Coerce a FrcScoredMatch to a TbaMatchSimple.
+ *
+ * NOTE: This function doesn't support Best of 3 currently.
+ * @param match
+ * @param year
+ * @param eventCode
+ */
+export function asTbaMatchSimple(match: FrcScoredMatch, year: string, eventCode: string): TbaMatchSimple {
+    const eventKey = getTbaEventKey(year, eventCode);
+    return {
+        alliances: {
+            blue: {
+                score: match.scoreBlueFinal ?? null,
+                team_keys: match.teams.filter(team =>
+                    team.station.includes("Blue"),
+                ).map(team => `frc${team.teamNumber}`),
+                dq_team_keys: match.teams.filter(team =>
+                    team.station.includes("Blue") && team.dq,
+                ).map(team => `frc${team.teamNumber}`),
+            },
+            red: {
+                score: match.scoreRedFinal ?? null,
+                team_keys: match.teams.filter(team =>
+                    team.station.includes("Red"),
+                ).map(team => `frc${team.teamNumber}`),
+                dq_team_keys: match.teams.filter(team =>
+                    team.station.includes("Red") && team.dq,
+                ).map(team => `frc${team.teamNumber}`),
+            },
+        },
+        comp_level: getTbaCompLevel(match.tournamentLevel, match.matchNumber),
+        match_number: match.matchNumber,
+        set_number: getTbaSetNumber(match.tournamentLevel, match.matchNumber),
+        winning_alliance: convertMatchWinnerToTba(match.scoreRedFinal, match.scoreBlueFinal),
+        event_key: eventKey,
+        key: getTbaMatchKey(match, eventKey),
+    };
+}
+
+export function getFrcApiMatchNumber(compLevel: CompLevel, setNumber: number | null, matchNumber: number): number {
+    if (compLevel === CompLevel.Qualification) {
+        return matchNumber;
+    }
+
+    // In double elimination, set number is the match number for the first 5 rounds
+    if (compLevel === CompLevel.Semifinal) {
+        if (!setNumber) {
+            throw new Error(`getFrcApiMatchNumber: setNumber cannot be null for ${compLevel} (note ` +
+                "that this function only works for events using double elims)");
+        }
+
+        return setNumber;
+    }
+
+    // In double elimination, the finals match numbers start at 14 (1 + 13)
+    if (compLevel === CompLevel.Final) {
+        return matchNumber + 13;
+    }
+
+    throw new Error(`getFrcApiMatchNumber: CompLevel ${compLevel} is not supported.`);
+}
diff --git a/server/src/models/frcEvents/frcScoredMatchesResponse.ts b/server/src/models/frcEvents/frcScoredMatchesResponse.ts
new file mode 100644
index 0000000..c50d671
--- /dev/null
+++ b/server/src/models/frcEvents/frcScoredMatchesResponse.ts
@@ -0,0 +1,5 @@
+import { type FrcScoredMatch } from "@src/models/frcEvents/frcScoredMatch";
+
+export interface FrcScoredMatchesResponse {
+    Matches: FrcScoredMatch[];
+}
diff --git a/server/src/models/frcEvents/frcTeam.ts b/server/src/models/frcEvents/frcTeam.ts
new file mode 100644
index 0000000..3bf474e
--- /dev/null
+++ b/server/src/models/frcEvents/frcTeam.ts
@@ -0,0 +1,5 @@
+export interface FrcTeam {
+    teamNumber: number;
+    station: string;
+    dq: boolean;
+}
diff --git a/server/src/models/frcEvents/frcTournamentLevel.ts b/server/src/models/frcEvents/frcTournamentLevel.ts
new file mode 100644
index 0000000..ea4f2be
--- /dev/null
+++ b/server/src/models/frcEvents/frcTournamentLevel.ts
@@ -0,0 +1,2 @@
+export type FrcTournamentLevel = "Qualification" | "Playoff";
+export type FrcApiTournamentLevel = "qual" | "playoff";
diff --git a/server/src/models/theBlueAlliance/tbaAlliance.ts b/server/src/models/theBlueAlliance/tbaAlliance.ts
index 745ae29..1daf5f8 100644
--- a/server/src/models/theBlueAlliance/tbaAlliance.ts
+++ b/server/src/models/theBlueAlliance/tbaAlliance.ts
@@ -3,6 +3,6 @@ import { type TbaFrcTeam } from "@src/models/theBlueAlliance/tbaFrcTeam";
 export interface TbaAlliance {
     dq_team_keys: TbaFrcTeam[];
     score: number | null;
-    surrogate_team_keys: TbaFrcTeam[];
+    surrogate_team_keys?: TbaFrcTeam[];
     team_keys: TbaFrcTeam[];
 }
diff --git a/server/src/repos/FrcEventsRepo.ts b/server/src/repos/FrcEventsRepo.ts
new file mode 100644
index 0000000..c4090c1
--- /dev/null
+++ b/server/src/repos/FrcEventsRepo.ts
@@ -0,0 +1,121 @@
+import {
+    type TbaMatchesSimpleApiResponse,
+    type TbaMatchSimple,
+} from "@src/models/theBlueAlliance/tbaMatchesSimpleApiResponse";
+import { isObject } from "@src/util/isObject";
+import { type FrcScoredMatchesResponse } from "@src/models/frcEvents/frcScoredMatchesResponse";
+import { asTbaMatchSimple, getFrcApiMatchNumber, isFrcScoredMatch } from "@src/models/frcEvents/frcScoredMatch";
+import logger from "jet-logger";
+import { type FrcApiTournamentLevel } from "@src/models/frcEvents/frcTournamentLevel";
+import type MatchKey from "@src/models/MatchKey";
+import { toFrcApiTournamentLevel } from "@src/models/CompLevel";
+
+export class FrcEventsRepo {
+    private readonly apiKey: string;
+    private readonly baseUrl = "https://frc-api.firstinspires.org/v3.0";
+
+    /**
+     *
+     * @param apiKey The base64-encoded Basic authentication API key to use with the FRC Events API
+     *
+     */
+    constructor(apiKey: string) {
+        this.apiKey = apiKey;
+    }
+
+    private async get<T extends object>(path: string, typeValidator: (x: unknown) => x is T): Promise<T> {
+        const url = `${this.baseUrl}/${path}`;
+        const result = await fetch(url, {
+            headers: {
+                Authorization: `Basic ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "User-Agent": "gafirst/match-uploader",
+            },
+        });
+
+        if (!result.ok) {
+            logger.err(`Error fetching ${url}: ${result.status} ${result.statusText}:`);
+            logger.err(await result.text());
+            throw new Error(`Error fetching ${url}: ${result.status} ${result.statusText}`);
+        }
+
+        const data: unknown = await result.json();
+
+        if (!typeValidator(data)) {
+            throw new Error(`Error fetching ${url}: response did not match expected type`);
+        }
+
+        return data;
+    }
+
+    private async getScoredMatchesForTournamentLevel(year: string,
+                                                     eventCode: string,
+                                                     tournamentLevel: FrcApiTournamentLevel,
+    ): Promise<TbaMatchSimple[]> {
+        try {
+            const result = await this.get(
+                `${year}/matches/${eventCode}?tournamentLevel=${tournamentLevel}`,
+                (elem): elem is FrcScoredMatchesResponse =>
+                    isObject(elem) &&
+                    !!(elem as FrcScoredMatchesResponse).Matches &&
+                    Array.isArray((elem as FrcScoredMatchesResponse).Matches) &&
+                    (elem as FrcScoredMatchesResponse).Matches.every(isObject) &&
+                    (elem as FrcScoredMatchesResponse).Matches.every(isFrcScoredMatch),
+            );
+
+            return result.Matches.map((match) => {
+                return asTbaMatchSimple(match, year, eventCode);
+            });
+        } catch (error) {
+            throw new Error(`Error fetching scored matches from FRC Events for ${year}${eventCode}: ${error}`);
+        }
+    }
+
+    /**
+     * Get scored matches for this event.
+     *
+     * Only returns qualification and playoff matches. Does not support best of 3 elimination matches.
+     *
+     * @param year The year associated with the event, e.g., 2023 for 2023gadal
+     * @param eventCode The event code, e.g., gadal for 2023gadal
+     */
+    async getScoredMatches(year: string, eventCode: string): Promise<TbaMatchesSimpleApiResponse> {
+        const [qualMatches, playoffMatches] = await Promise.all([
+            this.getScoredMatchesForTournamentLevel(year, eventCode, "qual"),
+            this.getScoredMatchesForTournamentLevel(year, eventCode, "playoff"),
+        ]);
+
+        return qualMatches.concat(playoffMatches);
+    }
+
+    async getScoredMatch(year: string, eventCode: string, matchKey: MatchKey): Promise<TbaMatchSimple> {
+        const tournamentLevel = toFrcApiTournamentLevel(matchKey.compLevel);
+        const matchNumber = getFrcApiMatchNumber(matchKey.compLevel, matchKey.setNumber, matchKey.matchNumber);
+
+        try {
+            const result = await this.get(
+                `${year}/matches/${eventCode}?tournamentLevel=${tournamentLevel}&matchNumber=${matchNumber}`,
+                (elem): elem is FrcScoredMatchesResponse =>
+                    isObject(elem) &&
+                    !!(elem as FrcScoredMatchesResponse).Matches &&
+                    Array.isArray((elem as FrcScoredMatchesResponse).Matches) &&
+                    (elem as FrcScoredMatchesResponse).Matches.every(isObject) &&
+                    (elem as FrcScoredMatchesResponse).Matches.every(isFrcScoredMatch),
+            );
+
+            // For some reason, the API response still has entries for every match even when matchNumber is spedified;
+            // the irrelevant entries have the import details nulled out and the respones is returned much faster
+            // though. Anyways, we can get around this easily enough using `find`
+            const match = result.Matches.find(match => match.matchNumber === matchNumber);
+
+            if (!match) {
+                throw new Error(`Match ${matchNumber} not found `);
+            }
+
+            return asTbaMatchSimple(match, year, eventCode);
+        } catch (error) {
+            throw new Error("getScoredMatch: Error fetching scored matches from FRC Events for " +
+                `${year}${eventCode}: ${error}`);
+        }
+    }
+}
diff --git a/server/src/routes/matches.ts b/server/src/routes/matches.ts
index abc32b0..54c5e65 100644
--- a/server/src/routes/matches.ts
+++ b/server/src/routes/matches.ts
@@ -4,7 +4,7 @@ import { type IReq, type IRes } from "@src/routes/types/types";
 import {
     generateMatchVideoDescription,
     getLocalVideoFilesForMatch,
-    getTbaMatchList,
+    getMatchList,
 } from "@src/services/MatchesService";
 import { matchedData, param, validationResult } from "express-validator";
 import MatchKey from "@src/models/MatchKey";
@@ -18,14 +18,14 @@ export const matchesRouter = Router();
 
 matchesRouter.get(
     Paths.Matches.List,
-    getMatchList,
+    getEventMatchList,
 );
 
-async function getMatchList(req: IReq, res: IRes): Promise<void> {
+async function getEventMatchList(req: IReq, res: IRes): Promise<void> {
     const { playoffsType: playoffsTypeRaw } = await getSettings();
     const playoffsType = playoffsTypeRaw as PlayoffsType;
 
-    const matchList = (await getTbaMatchList()).map((match) => {
+    const matchList = (await getMatchList()).map((match) => {
         return {
             key: match.key,
             verboseName: capitalizeFirstLetter(
diff --git a/server/src/services/MatchesService.ts b/server/src/services/MatchesService.ts
index 0b5ec1e..7f0c27d 100644
--- a/server/src/services/MatchesService.ts
+++ b/server/src/services/MatchesService.ts
@@ -8,6 +8,10 @@ import { type TbaMatchSimple } from "@src/models/theBlueAlliance/tbaMatchesSimpl
 import { TheBlueAllianceReadRepo } from "@src/repos/TheBlueAllianceReadRepo";
 import dedent from "dedent";
 import { type TbaFrcTeam } from "@src/models/theBlueAlliance/tbaFrcTeam";
+import { FrcEventsRepo } from "@src/repos/FrcEventsRepo";
+import { PlayoffsType } from "@src/models/PlayoffsType";
+import { getFrcApiMatchNumber } from "@src/models/frcEvents/frcScoredMatch";
+import { toFrcEventsUrlTournamentLevel } from "@src/models/CompLevel";
 
 export async function getLocalVideoFilesForMatch(matchKey: MatchKey): Promise<MatchVideoInfo[]> {
     const settings = await getSettings();
@@ -63,6 +67,28 @@ export async function getTbaMatchList(): Promise<TbaMatchSimple[]> {
     return await tba.getEventMatches(eventTbaCode);
 }
 
+export async function getFrcEventsMatchList(): Promise<TbaMatchSimple[]> {
+    const { eventTbaCode } = await getSettings();
+
+    const year = eventTbaCode.substring(0, 4);
+    const eventCode = eventTbaCode.substring(4);
+
+    const { frcEventsApiKey } = await getSecrets();
+    const frc = new FrcEventsRepo(frcEventsApiKey);
+
+    return await frc.getScoredMatches(year, eventCode);
+}
+
+export async function getMatchList(): Promise<TbaMatchSimple[]> {
+    const { useFrcEventsApi } = await getSettings();
+
+    if (useFrcEventsApi) {
+        return await getFrcEventsMatchList();
+    }
+
+    return await getTbaMatchList();
+}
+
 export async function getTbaMatch(matchKey: MatchKey): Promise<TbaMatchSimple> {
     const { theBlueAllianceReadApiKey } = await getSecrets();
     const tba = new TheBlueAllianceReadRepo(theBlueAllianceReadApiKey);
@@ -70,6 +96,28 @@ export async function getTbaMatch(matchKey: MatchKey): Promise<TbaMatchSimple> {
     return await tba.getMatchResults(matchKey);
 }
 
+export async function getFrcEventsMatch(matchKey: MatchKey): Promise<TbaMatchSimple> {
+    const { eventTbaCode } = await getSettings();
+
+    const year = eventTbaCode.substring(0, 4);
+    const eventCode = eventTbaCode.substring(4);
+
+    const { frcEventsApiKey } = await getSecrets();
+    const frc = new FrcEventsRepo(frcEventsApiKey);
+
+    return await frc.getScoredMatch(year, eventCode, matchKey);
+}
+
+export async function getMatch(matchKey: MatchKey): Promise<TbaMatchSimple> {
+    const { useFrcEventsApi } = await getSettings();
+
+    if (useFrcEventsApi) {
+        return await getFrcEventsMatch(matchKey);
+    }
+
+    return await getTbaMatch(matchKey);
+}
+
 /**
  * Determine if a match is scored. A match is scored if both alliances have a score greater than or equal to 0 set.
  * @param match The match object resulting from calling the TBA API using TheBlueAllianceReadRepo
@@ -90,15 +138,43 @@ function getTeamsInMatch(teamKeys: TbaFrcTeam[], joinWith = ", "): string {
     return teamKeys.map((teamKey) => teamKey.substring(3)).join(joinWith);
 }
 
+async function generateMatchDetailsUrl(matchKey: MatchKey): Promise<{
+    url: string,
+    site: "The Blue Alliance" | "FRC Events",
+}> {
+    const { eventTbaCode, useFrcEventsApi } = await getSettings();
+    const year = eventTbaCode.substring(0, 4);
+    const eventCode = eventTbaCode.substring(4);
+
+    if (useFrcEventsApi) {
+        if (matchKey.playoffsType !== PlayoffsType.DoubleElimination) {
+            throw new Error(`When using FRC Events as a data source, best of 3 matches are not supported.`);
+        }
+
+        const matchNumber = getFrcApiMatchNumber(matchKey.compLevel, matchKey.setNumber, matchKey.matchNumber);
+        const tournamentLevel = toFrcEventsUrlTournamentLevel(matchKey.compLevel);
+        return {
+            url: `https://frc-events.firstinspires.org/${year}/${eventCode}/${tournamentLevel}/${matchNumber}`,
+            site: "FRC Events",
+        };
+    }
+
+    return {
+        url: `https://thebluealliance.com/match/${matchKey.matchKey}`,
+        site: "The Blue Alliance",
+    };
+}
+
 export async function generateMatchVideoDescription(match: Match, eventName: string): Promise<string> {
     const matchKey = match.key;
-    const matchInfo = await getTbaMatch(matchKey);
+    const matchInfo = await getMatch(matchKey);
 
     if (!matchIsScored(matchInfo)) {
         throw new Error(`Match ${matchKey.matchKey} has not been scored yet.`);
     }
 
-    const matchTbaUrl = `https://thebluealliance.com/match/${matchKey.matchKey}`;
+    const { site: matchDetailsSite, url: matchUrl } = await generateMatchDetailsUrl(matchKey);
+
     // TODO: Don't hardcode references to GAFIRST
     const footageSource = `Footage of the ${eventName} is provided by the GeorgiaFIRST A/V Team.`;
     const socialMedia = "Follow us on Twitter (@GeorgiaFIRST) and Facebook " +
@@ -119,7 +195,7 @@ export async function generateMatchVideoDescription(match: Match, eventName: str
     Red (teams ${redTeams}) - ${redScore}
     Blue (teams ${blueTeams}) - ${blueScore}
     
-    View this match on The Blue Alliance: ${matchTbaUrl}
+    View this match on ${matchDetailsSite}: ${matchUrl}
     
     ${footageSource}
     
diff --git a/server/src/services/SettingsService.ts b/server/src/services/SettingsService.ts
index 762b3ec..6587e5f 100644
--- a/server/src/services/SettingsService.ts
+++ b/server/src/services/SettingsService.ts
@@ -50,6 +50,7 @@ export async function getObfuscatedSecrets(): Promise<ISecretSettingsHidden> {
     theBlueAllianceReadApiKey: false,
     theBlueAllianceTrustedApiAuthId: false,
     theBlueAllianceTrustedApiAuthSecret: false,
+    frcEventsApiKey: false,
   };
 
   for (const key in secrets) {