tbarequest 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael Kelbick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# TBArequest
+
+> Unofficial wrapper to request data from The Blue Alliance API
+
+
+> [!WARNING]  
+> This package relies on a beta version of Zod, so it might be unstable until Zod 4.0 comes out.
+
+## Install
+```bash
+npm install tbarequest
+```
+
+## Usage
+Use the `createTBACaller` function to create a function that can call the API.
+
+```ts
+import { createTBACaller } from "./index";
+
+const tba = createTBACaller("api_key")
+
+const status = tba("/status")
+const team = tba("/teams/{team_key}", 1014)
+```
+
+The `tba` function can call an endpoint and require all necessary arguments, and then return the results that are type-safe.
+
+Find all the endpoints [here](https://www.thebluealliance.com/apidocs/v3).
+
+## Coverage
+The wrapper covers all endpoints besides endpoints relating to Zebra Motionworks and Timeseries.
+The endpoints not covered include:
+* /event/{event_key}/matches/timeseries
+* /event/{event_key}/matches/timeseries
+* /match/{match_key}/timeseries
+* /match/{match_key}/zebra_motionworks

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+import { Result } from "./utils.js";
+import { TBAEndpoint, TBAEndpoints } from "./types/endpoints/index.js";
+export declare function createTBACaller(api_key: string): <T extends TBAEndpoint>(endpoint: T, ...args: z.infer<TBAEndpoints[T]["arguments"]>) => Promise<Result<z.infer<TBAEndpoints[T]["schema"]>>>;

package/dist/index.js

@@ -0,0 +1,46 @@
+import { tryCatch } from "./utils.js";
+import { endpoints } from "./types/endpoints/index.js";
+/*
+ * Creates a function that can call the TBA api.
+ * @see https://www.thebluealliance.com/apidocs/v3
+ * @param api_key The api key given to you from The Blue Alliance.
+ * @returns A function that can request from any endpoint in the TBA api. Go to the TBA api docs to see more information on endpoints and arguments required.
+ */
+export function createTBACaller(api_key) {
+    return async (endpoint, ...args) => await TBA(endpoint, api_key, ...args);
+}
+async function TBA(endpoint, api_key, ...args) {
+    let numArg = -1;
+    // Fills all the arguments that are needed.
+    const filledEndpoint = endpoint.replace(/{(.+?)}/g, () => {
+        numArg++;
+        return args[numArg].toString();
+    });
+    const result = await tryCatch(fetch(`https://www.thebluealliance.com/api/v3${filledEndpoint}`, {
+        headers: {
+            "X-TBA-Auth-Key": api_key,
+        },
+    }));
+    if (result.error)
+        return {
+            data: null, error: result.error,
+        };
+    if (result.data.status !== 200)
+        return {
+            data: null,
+            error: new Error(`${result.data.status} - ${result.data.statusText}`),
+        };
+    const json = await tryCatch(result.data.json());
+    if (json.error)
+        return {
+            data: null,
+            error: new Error(`JSON didn't parse for endpoint ${endpoint}. Please contact the developers of the TBArequest package with this error: ${json.error.message}`),
+        };
+    const schema = endpoints[endpoint].schema.safeParse(json.data);
+    if (!schema.success)
+        return {
+            data: null,
+            error: new Error(`Schema for endpoint ${endpoint} didn't work. Please contact the developers of the TBArequest package with this error: ${schema.error.message}`),
+        };
+    return { data: schema.data, error: null };
+}

package/dist/types/endpoints/districts.d.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+export declare const districtEndpoints: {
+    "/districts/{year}": {
+        schema: z.ZodArray<z.ZodObject<{
+            abbreviation: z.ZodString;
+            display_name: z.ZodString;
+            key: z.ZodString;
+            year: z.ZodInt;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodInt], null>;
+    };
+    "/district/{district_abbreviation}/history": {
+        schema: z.ZodArray<z.ZodObject<{
+            abbreviation: z.ZodString;
+            display_name: z.ZodString;
+            key: z.ZodString;
+            year: z.ZodInt;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/events": {
+        schema: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            name: z.ZodString;
+            city: z.ZodNullable<z.ZodString>;
+            state_prov: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+            postal_code: z.ZodNullable<z.ZodString>;
+            website: z.ZodNullable<z.ZodString>;
+            year: z.ZodInt;
+            event_code: z.ZodString;
+            event_type: z.ZodInt;
+            district: z.ZodNullable<z.ZodObject<{
+                abbreviation: z.ZodString;
+                display_name: z.ZodString;
+                key: z.ZodString;
+                year: z.ZodInt;
+            }, {}>>;
+            start_date: z.coerce.ZodCoercedDate;
+            end_date: z.coerce.ZodCoercedDate;
+            webcasts: z.ZodArray<z.ZodObject<{
+                type: z.ZodEnum<{
+                    youtube: "youtube";
+                    twitch: "twitch";
+                    ustream: "ustream";
+                    iframe: "iframe";
+                    html5: "html5";
+                    rtmp: "rtmp";
+                    livestream: "livestream";
+                    direct_link: "direct_link";
+                    mms: "mms";
+                    justin: "justin";
+                    stemtv: "stemtv";
+                    dacast: "dacast";
+                }>;
+                channel: z.ZodString;
+                date: z.ZodOptional<z.ZodNullable<z.coerce.ZodCoercedDate>>;
+                file: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, {}>>;
+            division_keys: z.ZodArray<z.ZodString>;
+            short_name: z.ZodNullable<z.ZodString>;
+            event_type_string: z.ZodString;
+            week: z.ZodNullable<z.ZodNumber>;
+            address: z.ZodNullable<z.ZodString>;
+            gmaps_place_id: z.ZodNullable<z.ZodString>;
+            gmaps_url: z.ZodNullable<z.ZodString>;
+            lat: z.ZodNullable<z.ZodNumber>;
+            lng: z.ZodNullable<z.ZodNumber>;
+            location_name: z.ZodNullable<z.ZodString>;
+            timezone: z.ZodNullable<z.ZodString>;
+            first_event_id: z.ZodNullable<z.ZodString>;
+            first_event_code: z.ZodNullable<z.ZodString>;
+            parent_event_key: z.ZodNullable<z.ZodString>;
+            playoff_type: z.ZodNullable<z.ZodInt>;
+            playoff_type_string: z.ZodNullable<z.ZodString>;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/awards": {
+        schema: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            award_type: z.ZodInt;
+            event_key: z.ZodString;
+            recipient_list: z.ZodArray<z.ZodObject<{
+                team_key: z.ZodNullable<z.ZodString>;
+                awardee: z.ZodNullable<z.ZodString>;
+            }, {}>>;
+            year: z.ZodInt;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/events/simple": {
+        schema: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            name: z.ZodString;
+            event_code: z.ZodString;
+            event_type: z.ZodInt;
+            district: z.ZodNullable<z.ZodObject<{
+                abbreviation: z.ZodString;
+                display_name: z.ZodString;
+                key: z.ZodString;
+                year: z.ZodInt;
+            }, {}>>;
+            city: z.ZodNullable<z.ZodString>;
+            state_prov: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+            start_date: z.coerce.ZodCoercedDate;
+            end_date: z.coerce.ZodCoercedDate;
+            year: z.ZodInt;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/events/keys": {
+        schema: z.ZodArray<z.ZodString>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/teams": {
+        schema: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            team_number: z.ZodInt;
+            nickname: z.ZodString;
+            name: z.ZodString;
+            city: z.ZodNullable<z.ZodString>;
+            state_prov: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+            postal_code: z.ZodNullable<z.ZodString>;
+            website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            rookie_year: z.ZodNullable<z.ZodNumber>;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/teams/simple": {
+        schema: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            team_number: z.ZodInt;
+            nickname: z.ZodString;
+            name: z.ZodString;
+            city: z.ZodNullable<z.ZodString>;
+            state_prov: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+        }, {}>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/teams/keys": {
+        schema: z.ZodArray<z.ZodString>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/rankings": {
+        schema: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            team_key: z.ZodString;
+            rank: z.ZodInt;
+            rookie_bonus: z.ZodOptional<z.ZodInt>;
+            point_total: z.ZodNumber;
+            event_points: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                district_cmp: z.ZodBoolean;
+                total: z.ZodNumber;
+                alliance_points: z.ZodNumber;
+                elim_points: z.ZodNumber;
+                award_points: z.ZodNumber;
+                event_key: z.ZodString;
+                qual_points: z.ZodNumber;
+            }, {}>>>;
+        }, {}>>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+    "/district/{district_key}/advancement": {
+        schema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+            dcmp: z.ZodBoolean;
+            cmp: z.ZodBoolean;
+        }, {}>>>;
+        arguments: z.ZodTuple<[z.ZodString], null>;
+    };
+};

package/dist/types/endpoints/districts.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { District_Advancement, District_List, District_Ranking } from "../schemas/districts.js";
+import { Event, Event_Simple } from "../schemas/events.js";
+import { Award, Team, Team_Simple } from "../schemas/teams.js";
+export const districtEndpoints = {
+    "/districts/{year}": {
+        schema: z.array(District_List),
+        arguments: z.tuple([z.int()]),
+    },
+    "/district/{district_abbreviation}/history": {
+        schema: z.array(District_List),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/events": {
+        schema: z.array(Event),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/awards": {
+        schema: z.array(Award),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/events/simple": {
+        schema: z.array(Event_Simple),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/events/keys": {
+        schema: z.array(z.string()),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/teams": {
+        schema: z.array(Team),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/teams/simple": {
+        schema: z.array(Team_Simple),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/teams/keys": {
+        schema: z.array(z.string()),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/rankings": {
+        schema: z.array(District_Ranking).nullable(),
+        arguments: z.tuple([z.string()]),
+    },
+    "/district/{district_key}/advancement": {
+        schema: z.record(z.string(), District_Advancement).nullable(),
+        arguments: z.tuple([z.string()]),
+    },
+};