tba

Instructions

Implementation Reference

• src/handlers.ts:923-939 (handler)

  The main handler logic for the 'get_district_events_simple' tool. Parses the input arguments, makes an API request to the TBA endpoint for simple district events, validates the response using EventSimpleSchema array, and returns the JSON-formatted events.

  case 'get_district_events_simple': {
    const { district_key } = z
      .object({ district_key: z.string() })
      .parse(args);
    const data = await makeApiRequest(
      `/district/${district_key}/events/simple`,
    );
    const events = z.array(EventSimpleSchema).parse(data);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(events, null, 2),
        },
      ],
    };
  }

• src/tools.ts:927-940 (registration)

  Tool registration object defining the name, description, and input schema for 'get_district_events_simple'. This array is returned by the list tools handler in index.ts.

  {
    name: 'get_district_events_simple',
    description: 'Get simplified events in a specific district',
    inputSchema: {
      type: 'object',
      properties: {
        district_key: {
          type: 'string',
          description: 'District key (e.g., 2023fim)',
        },
      },
      required: ['district_key'],
    },
  },

• src/schemas.ts:379-390 (schema)

  Zod schema used for validating the output events array in the handler. Defines the structure of simplified event objects from the TBA API.

  export const EventSimpleSchema = z.object({
    key: z.string(),
    name: z.string(),
    event_code: z.string(),
    event_type: z.number(),
    city: z.string().nullish(),
    state_prov: z.string().nullish(),
    country: z.string().nullish(),
    start_date: z.string(),
    end_date: z.string(),
    year: z.number(),
  });

• src/utils.ts:44-73 (helper)

  Utility function used by the handler to make authenticated requests to the TBA API v3, handling errors and logging.

  export async function makeApiRequest(endpoint: string): Promise<unknown> {
    try {
      const apiKey = getApiKey();
      const url = `https://www.thebluealliance.com/api/v3${endpoint}`;
  
      const response = await fetch(url, {
        headers: {
          'X-TBA-Auth-Key': apiKey,
          Accept: 'application/json',
        },
      });
  
      if (!response.ok) {
        const errorMessage = `TBA API request failed: ${response.status} ${response.statusText} for endpoint ${endpoint}`;
        await log('error', errorMessage);
        throw new Error(errorMessage);
      }
  
      return response.json();
    } catch (error) {
      if (error instanceof Error) {
        const errorMessage = `API request error for endpoint ${endpoint}: ${error.message}`;
        await log('error', errorMessage);
        throw error;
      }
      const errorMessage = `Unknown error during API request for endpoint ${endpoint}`;
      await log('error', `${errorMessage}: ${error}`);
      throw new Error(errorMessage);
    }
  }