index.ts

Filename	Percent	Threshold	Total	Covered	Uncovered
src/endpoints/index.ts	100.00%	80%	455	455	0

import {
  COUNTY_VOTE,
  DELEGATE_ALLOCATION,
  DELEGATE_VOTE,
  EDITORIAL_TURNOUT,
  ELECTORAL_VOTE,
  EST,
  MSG,
  NATIONAL_DELEGATE_SUMMARY,
  TOTAL_EXPECTED_VOTE,
} from '../constants/docTypes.js';
import { and, eq, inArray, isNull } from 'drizzle-orm';

import type { DB } from 'db/index.js';
import type { Logger } from 'winston';
import { Requests } from '../requests/index.js';
import type { components as apiComponents } from 'api.electiontonight';
import { streamPosition } from 'db/schema/streamPosition.js';

type ApiSchemas = apiComponents['schemas'];

type PositionedResponse<T> = {
  documents: T;
  /** The new stream position */
  newPosition: number;
  /** Whether the stream has been maxed out */
  maxed: boolean;
};

type Config = {
  apiKey: string;
  db: DB;
  eventId: string;
  logger?: Logger;
};

/**
 * Endpoints class includes methods that get data from ElectionTonight API endpoints.
 */
export class Endpoints extends Requests {
  eventId: string;
  db: DB;
  constructor({ logger, apiKey, eventId, db }: Config) {
    super({ logger, apiKey });
    this.eventId = eventId;
    this.db = db;
  }

  /**
   * Returns the documents data fetched from the ElectionTonight API endpoint and writes it as a local JSON file in the `temp` directory.
   *
   * @param path The path of the endpoint to fetch
   * @param params The query parameters to pass to the endpoint
   * @return The documents data returned from the endpoint
   */
  private async getEndpoint<T>(
    path: string = '',
    params: object = {}
  ): Promise<T[]> {
    const data = await this.getDocuments<T>(path, {
      params: { ...params, ...this.filter(), eventId: this.eventId },
    });
    return data;
  }

  /**
   * Returns the paginated documents data fetched from the ElectionTonight API paginated endpoint and writes it as a local JSON file in the `temp` directory.
   *
   * Unlike streams endpoints, which provide the position and numRecords parameters to consume the stream, other endpoint types such as Events and Results use a nextPage token along with the numRecords parameter for paging. Refer to the ElectionTonight API documentation for more information: https://subscriberdocs.electiontonight.com/guides/overview.html#endpoint-types
   *
   * @param path The path of the endpoint to fetch
   * @param params The query parameters to pass to the endpoint
   * @return The paginated documents data returned from the endpoint
   */
  private async getPaginatedEndpoint<T>(
    path = '',
    params = { numRecords: 100 }
  ): Promise<T[]> {
    const data = await this.getPaginatedDocuments<T>(path, {
      params: { ...params, ...this.filter(), eventId: this.eventId },
    });
    return data;
  }

  /**
   *  Gets documents from a position-based endpoint. Read more about how positions are used in streams endpoints in the ElectionTonight API documentation: https://subscriberdocs.electiontonight.com/guides/guide.html#streams
   *
   * @param path The path of the endpoint to fetch
   * @param params The query parameters to pass to the endpoint
   * @param position The position to start fetching documents from
   * @param maxRequests The maximum number of requests to make
   * @return An object containing the documents data returned from the endpoint, the new position, and whether the stream has been maxed out
   */
  private async getPositionedEndpoint<T>(
    path: string = '',
    params = { numRecords: 500 },
    position: number = 0,
    maxRequests: number = Infinity
  ): Promise<PositionedResponse<T[]>> {
    const {
      documents,
      position: newPosition,
      maxed,
    } = await this.getPositionedDocuments<T>(
      path,
      {
        params: {
          ...params,
          ...this.filter(),
          eventId: this.eventId,
          position,
        },
      },
      maxRequests
    );
    return { documents, newPosition, maxed };
  }

  /**
   * Returns a list of events and initialization versions for which there is data in the /events/* endpoints.
   */
  async getEvents() {
    return this.getPaginatedEndpoint<ApiSchemas['events']>('events', {
      numRecords: 500,
    });
  }

  /**
   * Returns documents fetched from the `events/absentee-method` endpoint, which contain metadata about absentee reporting methods.
   */
  async getEventsAbsenteeMethod() {
    return this.getPaginatedEndpoint<ApiSchemas['absentee-method']>(
      'events/absentee-method'
    );
  }

  /**
   * Returns documents fetched from the `events/county-by-elec` endpoint, which contain metadata about the counties and county pieces covered in an election, whether that is a statewide election, an election in a Congressional District or other jurisdiction. Note that the total precincts given in this document are advisory only. In rare cases, the total precincts may change on election night.
   */
  async getEventsCountyByElec() {
    return this.getPaginatedEndpoint<ApiSchemas['county-by-elec']>(
      'events/county-by-elec'
    );
  }

  /**
   * Returns documents fetched from the `events/county-by-state` endpoint, which contain county metadata data for a state. Information on which counties or pieces of counties are in a particular election is contained in the county-by-elect document.
   *
   * The term pseudo county is used to define a piece of a county. They may be used in some metropolitan areas where a county is split for reporting purposes (e.g. IL Cook county suburbs vs. City of Chicago).
   *
   * Note that the total precincts given in this document are advisory only. In rare cases, the total precincts may change on election night.
   */
  async getEventsCountyByState() {
    return this.getPaginatedEndpoint<ApiSchemas['county-by-state']>(
      'events/county-by-state'
    );
  }

  /**
   * Returns documents fetched from the `events/delegate-district` endpoint, which contain metadata about districts used to report on a particular election. Districts are linked to races through the race element of the election document.
   */
  async getEventsDelegateDistrict() {
    return this.getPaginatedEndpoint<ApiSchemas['delegate-district']>(
      'events/delegate-district'
    );
  }

  /**
   * Returns documents fetched from the `events/delegate-district-type` endpoint, which contain just the district type data about the districts used to report on a particular election. Districts are linked to races through the race element of the election document.
   */
  async getEventsDelegateDistrictType() {
    return this.getPaginatedEndpoint<ApiSchemas['delegate-district-type']>(
      'events/delegate-district-type'
    );
  }

  /**
   * Returns documents fetched from the `events/election` endpoint, which contain metadata about one election. It specifies past races of a specific election type for a given election date, state, and jurisdiction.
   */
  async getEventsElection() {
    return this.getPaginatedEndpoint<ApiSchemas['election']>('events/election');
  }

  /**
   * Returns documents fetched from the `events/election-race` endpoint, which contain metadata about races such as candidates and their parties.
   */
  async getEventsElectionRace() {
    return this.getPaginatedEndpoint<ApiSchemas['election-race']>(
      'events/election/race'
    );
  }

  /**
   * Returns documents fetched from the `events/party-by-office` endpoint, which contain metadata needed to calculate the change in power between the major parties for a given office. This data is provided for the U.S. Senate, Governor, and U.S. House.
   */
  async getEventsPartyByOffice() {
    return this.getPaginatedEndpoint<ApiSchemas['party-by-office']>(
      'events/party-by-office'
    );
  }

  /**
   * Returns documents fetched from the `events/party-lookup` endpoint, which contain metadata about political parties.
   */
  async getEventsPartyLookup() {
    return this.getPaginatedEndpoint<ApiSchemas['party-lookup']>(
      'events/party-lookup'
    );
  }

  /**
   * Returns documents fetched from the `events/past-county-data` endpoint, which contain historical vote counts by county.
   */
  async getEventsPastCountyData() {
    return this.getPaginatedEndpoint<ApiSchemas['past-county-data']>(
      'events/past-county-data'
    );
  }

  /**
   * Returns documents fetched from the `events/xtab-setup` endpoint, which contain metadata about the xTab (exit poll cross tabulation) document that will be available on election day.
   *
   * Each xtab-setup document deals with a pre-defined set of exit poll cross tabulations for one race. The optional subsets are for sending filtered data such as "Male Only", "Female Only", "New England", etc.
   */
  async getEventsXtabSetup() {
    return this.getPaginatedEndpoint<ApiSchemas['xtab-setup']>(
      'events/xtab-setup'
    );
  }

  /**
   * Returns documents fetched from the `results/county-vote` endpoint, which contain the latest county votes data.
   *
   * A vote document sends vote results for a single, unique contest and can accommodate results at any level of granularity. Granularity is determined by the `scp` (scope) tag. Race-wide summaries are `scp=S`, county votes are `scp=C`.
   */
  async getResultsCountyVote() {
    return this.getPaginatedEndpoint<ApiSchemas['county-vote']>(
      'results/county-vote'
    );
  }

  /**
   * Returns documents fetched from the `results/delegate-allocation` endpoint, which contain data on delegate allocations.
   */
  async getResultsDelegateAllocation() {
    return this.getPaginatedEndpoint<ApiSchemas['delegate-allocation']>(
      'results/delegate-allocation'
    );
  }

  /**
   * Returns documents fetched from the `results/delegate-vote` endpoint, which contain data on district votes.
   *
   * @TODO - check whether it's district votes or delegate votes. Shouldn't each candidate in each district have a delegate vote count?
   */
  async getResultsDelegateVote() {
    return this.getPaginatedEndpoint<ApiSchemas['delegate-vote']>(
      'results/delegate-vote'
    );
  }

  /**
   * Returns documents fetched from the `results/editorial-turnout` endpoint, which contain data on the voting-eligible population and, optionally, turnout as a percentage of the voting-age population.
   */
  async getResultsEditorialTurnout() {
    return this.getPaginatedEndpoint<ApiSchemas['editorial-turnout']>(
      'results/editorial-turnout'
    );
  }

  /**
   * Returns documents fetched from the `results/electoral-vote` endpoint, which contain data on electoral vote allocations.
   */
  async getResultsElectoralVote() {
    return this.getPaginatedEndpoint<ApiSchemas['electoral-vote']>(
      'results/electoral-vote'
    );
  }

  /**
   * Returns documents fetched from the `results/est` endpoint, which contain contain ENS race calls for a single, unique contest.
   *
   * Within this document the `cStat` (call status) field will be set to either W for winner, R for reversal, or V for advances-to-runoff.
   */
  async getResultsEst() {
    return this.getPaginatedEndpoint<ApiSchemas['est']>('results/est');
  }

  /**
   * Returns documents fetched from the `results/msg` endpoint, which contain contain election messages from the EAS.
   *
   * These messages are used to commumicate important information such as an increase in total expected vote or a weather problem that is delaying vote count collection.
   */
  async getResultsMsg() {
    return this.getPaginatedEndpoint<ApiSchemas['msg']>('results/msg');
  }

  /**
   * Returns documents fetched from the `results/national-delegate-summary` endpoint, which contain summary data of the delegate allocations for the current primary cycle.
   */
  async getResultsNationalDelegateSummary() {
    return this.getPaginatedEndpoint<ApiSchemas['national-delegate-summary']>(
      'results/national-delegate-summary'
    );
  }

  /**
   * Returns documents fetched from the `results/total-expected-vote` endpoint, which contain the total expected vote estimate for a county and election.
   *
   * The documents also contain other information regarding the status of that county's total vote count.
   */
  async getResultsTotalExpectedVote() {
    return this.getPaginatedEndpoint<ApiSchemas['total-expected-vote']>(
      'results/total-expected-vote'
    );
  }

  /**
   * Returns a list of all the streams endpoints and their current max position.
   *
   * Streams support getting data as soon as it becomes available. Clients will poll making HTTPS GET requests. Results sent back to the client will include a metadata attribute called nextPosition, which signifies to clients where there are at in the stream. Subsequent requests and include this as query parameter position to signify the next document in the stream to continue from. When you’ve reached the end of the stream, you receive an empty container of documents and the nextPosition pointer does not change.
   *
   * Documents on the stream may be out of order when viewed by their sequence number (seq attribute). Refer to the ElectionTonight API documentation for more information: https://subscriberdocs.electiontonight.com/guides/overview.html#overview-streams
   */
  async getStreams() {
    return this.getEndpoint<ApiSchemas['streams']>('streams');
  }

  /**
   * Gets the earliest stream position for a particular doc type, taking into account filters.
   * @param docType doc type constant
   * @returns Earliest stream position
   */
  async getStreamPositionForDocType(docType: string) {
    const filters = this.filter();
    if (!filters) return;
    const { st: filterSt, ofc: filterOfc, scp: filterScp } = filters;
    /**
     * First check for stream position matching the specific filter
     */
    let streamPositions = await this.db
      .select({
        maxPosition: streamPosition.maxPosition,
      })
      .from(streamPosition)
      .where(
        and(
          eq(streamPosition.docType, docType),
          eq(streamPosition.filterScp, filterScp),
          filterOfc
            ? eq(streamPosition.filterOfc, filterOfc)
            : isNull(streamPosition.filterOfc),
          filterSt
            ? inArray(streamPosition.filterSt, filterSt.split(','))
            : isNull(streamPosition.filterSt)
        )
      );

    /**
     * If no stream positions were found with a filtered query, we try
     * to find an unfiltered stream position that would supersede it.
     */

    /**
     * First try a position without an office filter ...
     */
    if (streamPositions.length === 0 && filterOfc) {
      streamPositions = await this.db
        .select({
          maxPosition: streamPosition.maxPosition,
        })
        .from(streamPosition)
        .where(
          and(
            eq(streamPosition.docType, docType),
            eq(streamPosition.filterScp, filterScp),
            isNull(streamPosition.filterOfc),
            filterSt
              ? inArray(streamPosition.filterSt, filterSt.split(','))
              : isNull(streamPosition.filterSt)
          )
        );
    }
    /**
     * ... next, one without a state filter.
     */
    if (streamPositions.length === 0 && filterSt) {
      streamPositions = await this.db
        .select({
          maxPosition: streamPosition.maxPosition,
        })
        .from(streamPosition)
        .where(
          and(
            eq(streamPosition.docType, docType),
            eq(streamPosition.filterScp, filterScp),
            filterOfc
              ? eq(streamPosition.filterOfc, filterOfc)
              : isNull(streamPosition.filterOfc),
            isNull(streamPosition.filterSt)
          )
        );
    }

    if (streamPositions.length === 0) return 0;

    /**
     * Get the minimum maxPosition for this set of filters, i.e., we want
     * the oldest document so we're sure we don't miss any documents returned
     * by this set of filters.
     */
    const minMaxPosition = Math.min(
      ...streamPositions.map((sp) => sp.maxPosition)
    );
    return minMaxPosition;
  }

  /**
   * Returns streamed documents fetched from the `results/county-vote` endpoint, which contain the latest county votes data at the earliest stream position for a particular doc type.
   *
   * A vote document sends vote results for a single, unique contest and can accommodate results at any level of granularity. Granularity is determined by the `scp` (scope) tag. Race-wide summaries are `scp=S`, county votes are `scp=C`.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsCountyVote(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(COUNTY_VOTE);
    return this.getPositionedEndpoint<ApiSchemas['county-vote']>(
      'streams/county-vote',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/delegate-allocation` endpoint, which contain data on delegate allocations at the earliest stream position for a particular doc type.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsDelegateAllocation(maxRequests = Infinity) {
    const position =
      await this.getStreamPositionForDocType(DELEGATE_ALLOCATION);
    return this.getPositionedEndpoint<ApiSchemas['delegate-allocation']>(
      'streams/delegate-allocation',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/delegate-vote` endpoint, which contain data on district votes at the earliest stream position for a particular doc type.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsDelegateVote(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(DELEGATE_VOTE);
    return this.getPositionedEndpoint<ApiSchemas['delegate-vote']>(
      'streams/delegate-vote',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/editorial-turnout` endpoint, which contain data on the voting-eligible population and, optionally, turnout as a percentage of the voting-age population at the earliest stream position for a particular doc type.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsEditorialTurnout(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(EDITORIAL_TURNOUT);
    return this.getPositionedEndpoint<ApiSchemas['editorial-turnout']>(
      'streams/editorial-turnout',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/est` endpoint, which contain contain ENS race calls for a single, unique contest at the earliest stream position for a particular doc type.
   *
   * Within this document the `cStat` (call status) field will be set to either W for winner, R for reversal, or V for advances-to-runoff.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsEst(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(EST);
    return this.getPositionedEndpoint<ApiSchemas['est']>(
      'streams/est',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/msg` endpoint, which contain contain election messages from the EAS at the earliest stream position for a particular doc type.
   *
   * These messages are used to commumicate important information such as an increase in total expected vote or a weather problem that is delaying vote count collection.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsMsg(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(MSG);
    return this.getPositionedEndpoint<ApiSchemas['msg']>(
      'streams/msg',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/national-delegate-summary` endpoint, which contain summary data of the delegate allocations for the current primary cycle at the earliest stream position for a particular doc type.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsNationalDelegateSummary(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(
      NATIONAL_DELEGATE_SUMMARY
    );
    return this.getPositionedEndpoint<ApiSchemas['national-delegate-summary']>(
      'streams/national-delegate-summary',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/total-expected-vote` endpoint, which contain the total expected vote estimate for a county and election at the earliest stream position for a particular doc type.
   *
   * The documents also contain other information regarding the status of that county's total vote count.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsTotalExpectedVote(maxRequests = Infinity) {
    const position =
      await this.getStreamPositionForDocType(TOTAL_EXPECTED_VOTE);
    return this.getPositionedEndpoint<ApiSchemas['total-expected-vote']>(
      'streams/total-expected-vote',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }

  /**
   * Returns streamed documents fetched from the `results/electoral-vote` endpoint.
   *
   * @param maxRequests The maximum number of requests to make
   */
  async getStreamsElectoralVote(maxRequests = Infinity) {
    const position = await this.getStreamPositionForDocType(ELECTORAL_VOTE);
    return this.getPositionedEndpoint<ApiSchemas['electoral-vote']>(
      'streams/electoral-vote',
      { numRecords: 500 },
      position,
      maxRequests
    );
  }
}

[]

TypeScript coverage report