elections-types 1.0.0

package/eslint.config.ts

@@ -0,0 +1,13 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+    { files: ["**/*.{js,mjs,cjs,ts,mts,cts}"], plugins: { js }, extends: ["js/recommended"], languageOptions: { globals: globals.browser } },
+    {
+		rules: {
+            "@typescript-eslint/explicit-function-return-type": "error"
+		},
+	},
+]);

package/jest.config.js

@@ -0,0 +1,20 @@
+import { createDefaultPreset } from "ts-jest"
+
+const tsJestTransformCfg = createDefaultPreset().transform;
+
+/** @type {import("jest").Config} **/
+export default {
+    testEnvironment: "node",
+    transform: {
+        ...tsJestTransformCfg,
+    },
+    transformIgnorePatterns: ["/node_modules/(?!@smithy|@aws-sdk).+\\.js$"],
+    globals : {
+        "ts-jest" : {
+            useESM : true
+        }
+    },
+    extensionsToTreatAsEsm : [".ts"],
+    testTimeout : 30000,
+    testPathIgnorePatterns: ['dist/']
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "elections-types",
+    "version": "1.0.0",
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "directories": {
+        "test": "test"
+    },
+    "scripts": {
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+        "build": "tsc && tsc-alias"
+    },
+    "author": "",
+    "license": "ISC",
+    "description": "",
+    "type": "module",
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "@types/jest": "^30.0.0",
+        "eslint": "^9.39.2",
+        "globals": "^17.3.0",
+        "jest": "^30.2.0",
+        "jiti": "^2.6.1",
+        "ts-jest": "^29.4.6",
+        "tsc-alias": "^1.8.16",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.55.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types/APIError"
+export * from "./types/Tweet"
+export * from "./types/User"

package/src/types/APIError.ts

@@ -0,0 +1,21 @@
+const default_messages_by_status : Record<number, string> = {
+    400 : "Bad Request",
+    401 : "Unauthorized",
+    403 : "Forbidden",
+    404 : "Not Found",
+    405 : "Method Not Allowed",
+    500 : "Internal Server Error",
+    504 : "Gateway Timeout",
+    600 : "Failed to Parse Output"
+}
+
+
+export class APIError extends Error {
+    status : number
+    constructor(status : number, message?: string) {
+        const default_message = default_messages_by_status[status]
+        super(message !== undefined ? message : default_message !== undefined ? default_message : "Error")
+        this.name = "APIError"
+        this.status = status
+    }
+}

package/src/types/Candidate.ts

@@ -0,0 +1,52 @@
+// import { ElectionID, OfficeID } from "./Election"
+// import { StateID } from "./State"
+
+// export class Candidate {
+//     readonly candidate_id : string
+//     readonly fec_name : string
+//     readonly office_id : OfficeID
+//     readonly state_id : StateID
+//     readonly election_id : ElectionID
+//     readonly party_id : string
+//     readonly active : boolean
+//     readonly status : boolean
+
+//     constructor(candidate : any) {
+//         if (!Candidate.is(candidate)) {
+//             throw Error("Invalid input.")
+//         }
+//         this.office_id = candidate.office_id
+//         this.number = candidate.number
+//         this.scout_id = candidate.scout_id
+//         this.name = candidate.name
+//         this.active = candidate.active
+//         this.state_id = candidate.state_id
+//         this.district = candidate.district
+//         this.party_id = candidate.party_id
+//         this.tone_description_refresh = candidate.tone_description_refresh
+//         this.jurisdiction_ids = candidate.jurisdiction_ids
+//         this.sub_scout_ids = candidate.sub_scout_ids
+//         this.office_class_id = candidate.office_class_id
+//         this.office_name = candidate.office_name
+//     }
+
+//     static is(candidate : any) : candidate is Candidate {
+//         return (
+//             candidate !== undefined &&
+//             typeof candidate.office_id === "string" &&
+//             typeof candidate.number === "string" &&
+//             typeof candidate.scout_id === "string" &&
+//             typeof candidate.name === "string" &&
+//             typeof candidate.active === "boolean" &&
+//             (candidate.state_id === undefined || is_state_id(candidate.state_id)) &&
+//             (candidate.district === undefined || typeof candidate.district === "number") &&
+//             is_party_id(candidate.party_id) &&
+//             typeof candidate.tone_description_refresh === "boolean" &&
+//             Array.isArray(candidate.jurisdiction_ids) &&
+//             candidate.jurisdiction_ids.every((jurisdiction_id : any) => typeof jurisdiction_id === "number") &&
+//             (candidate.sub_scout_ids === undefined || Array.isArray(candidate.sub_scout_ids) && candidate.sub_scout_ids.every((sub_scout_id : any) => typeof sub_scout_id === "string")) &&
+//             is_office_class_id(candidate.office_class_id) &&
+//             (candidate.office_name === undefined || typeof candidate.office_name === "string")
+//         )
+//     }
+// }

package/src/types/Committee.ts

@@ -0,0 +1,62 @@
+export const designations = ["F1", "F2", "F3", "F24"] as const
+
+export type CommitteeDesignation = typeof designations[number]
+
+export function is_committee_designation(designation : any) : designation is CommitteeDesignation {
+    return designations.includes(designation)
+}
+
+export class Committee {
+    readonly committee_id : string
+    readonly name : string
+    readonly url : string
+    readonly designation : CommitteeDesignation
+    readonly file_number : number
+    readonly principal_committee_ids? : string[]
+    readonly authorized_committee_ids? : string[]
+    readonly sponsor_committee_ids? : string[]
+    readonly jfp_committee_ids? : string[]
+    readonly jfr_committee_ids? : string[]
+    readonly aff_committee_ids? : string[]
+    readonly candidate_ids? : string[]
+    readonly election_ids? : string[]
+    readonly [x : string] : any
+
+    constructor(committee : any) {
+        if (!Committee.is(committee)) {
+            throw Error("Invalid input.")
+        }
+        this.committee_id = committee.committee_id
+        this.name = committee.name
+        this.url = committee.url
+        this.designation = committee.designation
+        this.file_number = committee.file_number
+        this.principal_committee_ids = committee.principal_committee_ids
+        this.authorized_committee_ids = committee.authorized_committee_ids
+        this.sponsor_committee_ids = committee.sponsor_committee_ids
+        this.jfp_committee_ids = committee.jfp_committee_ids
+        this.jfr_committee_ids = committee.jfr_committee_ids
+        this.aff_committee_ids = committee.aff_committee_ids
+        this.candidate_ids = committee.candidate_ids
+        this.election_ids = committee.election_ids
+    }
+
+    static is(committee : any) : committee is Committee {
+        return (
+            committee !== undefined &&
+            typeof committee.committee_id === "string" &&
+            typeof committee.name === "string" &&
+            typeof committee.url === "string" &&
+            is_committee_designation(committee.designation) &&
+            typeof committee.file_number === "number" &&
+            (committee.principal_committee_ids === undefined || Array.isArray(committee.principal_committee_ids) && committee.principal_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.authorized_committee_ids === undefined || Array.isArray(committee.authorized_committee_ids) && committee.authorized_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.sponsor_committee_ids === undefined || Array.isArray(committee.sponsor_committee_ids) && committee.sponsor_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.jfp_committee_ids === undefined || Array.isArray(committee.jfp_committee_ids) && committee.jfp_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.jfr_committee_ids === undefined || Array.isArray(committee.jfr_committee_ids) && committee.jfr_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.aff_committee_ids === undefined || Array.isArray(committee.aff_committee_ids) && committee.aff_committee_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.candidate_ids === undefined || Array.isArray(committee.candidate_ids) && committee.candidate_ids.every((committee_id : any) => typeof committee_id === "string")) &&
+            (committee.election_ids === undefined || Array.isArray(committee.election_ids) && committee.election_ids.every((committee_id : any) => typeof committee_id === "string"))
+        )
+    }
+}

package/src/types/Election.ts

@@ -0,0 +1,62 @@
+import { is_state_id, state_ids, StateID } from "./State"
+
+const office_ids = ["H", "S"] as const
+
+export type OfficeID = typeof office_ids[number]
+
+export function is_office_id(office_id : any) : office_id is OfficeID {
+    return office_ids.includes(office_id)
+}
+
+export type ElectionID = string
+
+export function is_election_id(election_id : any) : election_id is ElectionID {
+    const parts = election_id.split("-")
+    const year = Number(parts[0])
+    const office_id = parts[1]
+    const state_id = parts[2]
+    const district = Number(parts[3])
+    return (
+        (parts.length === 4 && office_id === "H" || parts.length === 3) &&
+        Number.isInteger(year) && year > 1700 && year < 3000 &&
+        is_office_id(office_id) &&
+        is_state_id(state_id) &&
+        (office_id === "S" || Number.isInteger(district) && district < 100)
+    )
+}
+
+export class Election {
+    readonly election_id : ElectionID
+    readonly name : string
+    readonly office_id : OfficeID
+    readonly state_id : StateID
+    readonly district? : string
+    readonly candidate_ids? : string[]
+    readonly committee_ids? : string[]
+
+    constructor(election : any) {
+        if (!Election.is(election)) {
+            throw Error("Invalid input.")
+        }
+        this.election_id = election.election_id
+        this.name = election.name
+        this.office_id = election.office_id
+        this.state_id = election.state_id
+        this.district = election.district
+        this.candidate_ids = election.candidate_ids
+        this.committee_ids = election.committee_ids
+    }
+
+    static is(election : any) : election is Election {
+        return (
+            election !== undefined &&
+            is_election_id(election.election_id) &&
+            typeof election.name === "string" &&
+            is_office_id(election.office_id) &&
+            is_state_id(election.state_id) &&
+            (election.district === undefined && typeof election.district === "string") &&
+            (election.candidate_ids === undefined || Array.isArray(election.candidate_ids) && election.candidate_ids.every((candidate_id : any) => typeof candidate_id === "string")) &&
+            (election.committee_ids === undefined || Array.isArray(election.committee_ids) && election.committee_ids.every((committee_id : any) => typeof committee_id === "string"))
+        )
+    }
+}

package/src/types/ElectionsConfig.ts

@@ -0,0 +1,23 @@
+export interface ElectionsUtilsConfig {
+    region : string,
+    scraping_bee_api_key? : string,
+    xai_api_key? : string,
+    citizenportal_api_key? : string,
+    youtube_api_key? : string
+    [key : string]: any
+}
+
+export interface ElectionsConfig extends ElectionsUtilsConfig {
+    port : number,
+    api_url : string,
+    client_url : string,
+    auth_url : string,
+    cognito_user_pool_id : string,
+    cognito_client_id : string,
+    cognito_client_secret : string,
+    secret_key : string,
+    // admin_key : string,
+    dynamodb_donations : string,
+    s3_bucket : string,
+    s3vectors_bucket : string
+}

package/src/types/FormTypeID.ts

@@ -0,0 +1,20 @@
+export const form_type_ids = ["F1", "F2", "F3", "F24"] as const
+
+export type FormTypeID = typeof form_type_ids[number]
+
+export function is_form_type_id(form_type_id : any) : form_type_id is FormTypeID {
+    return form_type_ids.includes(form_type_id)
+}
+
+export const long_form_type_ids = [
+    "F1N", "F1A", "F1T",
+    "F2N", "F2A", "F2T",
+    "F3N", "F3A", "F3T",
+    "F24N", "F24A"
+] as const
+
+export type LongFormTypeID = typeof long_form_type_ids[number]
+
+export function is_long_form_type_id(long_form_type_id : any) : long_form_type_id is LongFormTypeID {
+    return long_form_type_ids.includes(long_form_type_id)
+}

package/src/types/State.ts

@@ -0,0 +1,215 @@
+export const state_ids = ["AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY"] as const
+
+export type StateID = typeof state_ids[number]
+
+export function is_state_id(state_id : any) : state_id is StateID {
+    return state_ids.includes(state_id)
+}
+
+export interface State {
+    state_id : StateID,
+    name : string
+}
+
+export const states_by_state_id : Record<StateID, State> = {
+    AL : {
+        state_id : "AL",
+        name : "Alabama"
+    },
+    AK : {
+        state_id : "AK",
+        name : "Alaska"
+    },
+    AZ : {
+        state_id : "AZ",
+        name : "Arizona"
+    },
+    AR : {
+        state_id : "AR",
+        name : "Arkansas"
+    },
+    CA : {
+        state_id : "CA",
+        name : "California"
+    },
+    CO : {
+        state_id : "CO",
+        name : "Colorado"
+    },
+    CT : {
+        state_id : "CT",
+        name : "Connecticut"
+    },
+    DE : {
+        state_id : "DE",
+        name : "Delaware"
+    },
+    FL : {
+        state_id : "FL",
+        name : "Florida"
+    },
+    GA : {
+        state_id : "GA",
+        name : "Georgia"
+    },
+    HI : {
+        state_id : "HI",
+        name : "Hawaii"
+    },
+    ID : {
+        state_id : "ID",
+        name : "Idaho"
+    },
+    IL : {
+        state_id : "IL",
+        name : "Illinois"
+    },
+    IN : {
+        state_id : "IN",
+        name : "Indiana"
+    },
+    IA : {
+        state_id : "IA",
+        name : "Iowa"
+    },
+    KS : {
+        state_id : "KS",
+        name : "Kansas"
+    },
+    KY : {
+        state_id : "KY",
+        name : "Kentucky"
+    },
+    LA : {
+        state_id : "LA",
+        name : "Louisiana"
+    },
+    ME : {
+        state_id : "ME",
+        name : "Maine"
+    },
+    MD : {
+        state_id : "MD",
+        name : "Maryland"
+    },
+    MA : {
+        state_id : "MA",
+        name : "Massachusetts"
+    },
+    MI : {
+        state_id : "MI",
+        name : "Michigan"
+    },
+    MN : {
+        state_id : "MN",
+        name : "Minnesota"
+    },
+    MS : {
+        state_id : "MS",
+        name : "Mississippi"
+    },
+    MO : {
+        state_id : "MO",
+        name : "Missouri"
+    },
+    MT : {
+        state_id : "MT",
+        name : "Montana"
+    },
+    NE : {
+        state_id : "NE",
+        name : "Nebraska"
+    },
+    NV : {
+        state_id : "NV",
+        name : "Nevada"
+    },
+    NH : {
+        state_id : "NH",
+        name : "New Hampshire"
+    },
+    NJ : {
+        state_id : "NJ",
+        name : "New Jersey"
+    },
+    NM : {
+        state_id : "NM",
+        name : "New Mexico"
+    },
+    NY : {
+        state_id : "NY",
+        name : "New York"
+    },
+    NC : {
+        state_id : "NC",
+        name : "North Carolina"
+    },
+    ND : {
+        state_id : "ND",
+        name : "North Dakota"
+    },
+    OH : {
+        state_id : "OH",
+        name : "Ohio"
+    },
+    OK : {
+        state_id : "OK",
+        name : "Oklahoma"
+    },
+    OR : {
+        state_id : "OR",
+        name : "Oregon"
+    },
+    PA : {
+        state_id : "PA",
+        name : "Pennsylvania"
+    },
+    RI : {
+        state_id : "RI",
+        name : "Rhode Island"
+    },
+    SC : {
+        state_id : "SC",
+        name : "South Carolina"
+    },
+    SD : {
+        state_id : "SD",
+        name : "South Dakota"
+    },
+    TN : {
+        state_id : "TN",
+        name : "Tennessee"
+    },
+    TX : {
+        state_id : "TX",
+        name : "Texas"
+    },
+    UT : {
+        state_id : "UT",
+        name : "Utah"
+    },
+    VT : {
+        state_id : "VT",
+        name : "Vermont"
+    },
+    VA : {
+        state_id : "VA",
+        name : "Virginia"
+    },
+    WA : {
+        state_id : "WA",
+        name : "Washington"
+    },
+    WV : {
+        state_id : "WV",
+        name : "West Virginia"
+    },
+    WI : {
+        state_id : "WI",
+        name : "Wisconsin"
+    },
+    WY : {
+        state_id : "WY",
+        name : "Wyoming"
+    }
+}

package/src/types/Tweet.ts

@@ -0,0 +1,38 @@
+export class Tweet {
+    readonly tweet_id : string
+    readonly username : string
+    readonly url : string
+    readonly tweet_time : string
+    readonly tweet_content : string
+    readonly quote? : string
+    readonly html : string
+    readonly text : string
+
+    constructor(tweet : any) {
+        if (!Tweet.is(tweet)) {
+            throw Error("Invalid input.")
+        }
+        this.tweet_id = tweet.tweet_id
+        this.username = tweet.username
+        this.url = tweet.url
+        this.tweet_time = tweet.tweet_time
+        this.tweet_content = tweet.tweet_content
+        this.quote = tweet.quote
+        this.html = tweet.html
+        this.text = tweet.text
+    }
+
+    static is(tweet : any) : tweet is Tweet {
+        return (
+            tweet !== undefined &&
+            typeof tweet.tweet_id === "string" &&
+            typeof tweet.username === "string" &&
+            typeof tweet.url === "string" &&
+            typeof tweet.tweet_time === "string" &&
+            typeof tweet.tweet_content === "string" &&
+            (tweet.quote === undefined || typeof tweet.quote === "string") &&
+            (typeof tweet.html === "string") &&
+            (typeof tweet.text === "string")
+        )
+    }
+}

package/src/types/User.ts

@@ -0,0 +1,34 @@
+import { is_long_form_type_id, LongFormTypeID } from "./FormTypeID"
+
+export class User {
+    readonly user_id : string
+    readonly admin : boolean
+    readonly premium : boolean
+    readonly email : string
+    readonly email_settings : Record<LongFormTypeID, boolean>
+    // readonly [x : string] : any
+
+    constructor(user : any) {
+        if (!User.is(user)) {
+            throw Error("Invalid Input.")
+        }
+        this.user_id = user.user_id
+        this.admin = user.admin
+        this.premium = user.premium
+        this.email = user.email
+        this.email_settings = user.email_settings
+    }
+
+    static is(user : any) : user is User {
+        return (
+            user !== undefined &&
+            typeof user.user_id === "string" &&
+            typeof user.admin === "boolean" &&
+            typeof user.premium === "boolean" &&
+            typeof user.email === "string" &&
+            Array.isArray(user.scout_ids) &&
+            typeof user.email_settings === "object" &&
+            Object.entries(user.email_settings).every(([key, value]) => is_long_form_type_id(key) && typeof value === "boolean")
+        )
+    }
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+	"compilerOptions": {
+        "outDir": "./dist",
+
+		// Treat files as modules even if it doesn't use import/export
+		"moduleDetection": "force",
+
+		// Ignore module structure
+		"module" : "esnext",
+        "target" : "es2022",
+        "noImplicitAny" : true,
+        "noImplicitReturns" : true,
+        "moduleResolution": "bundler",
+        "declaration": true,
+		// Allow JS files to be imported from TS and vice versa
+		"allowJs": true,
+        "strict" : true,
+		// Use correct ESM import behavior
+		"esModuleInterop": true,
+        "resolveJsonModule": true,
+		// Disallow features that require cross-file awareness
+		"isolatedModules": true,
+    	"lib": ["es2022"],
+        "rootDir": "./",
+        "skipLibCheck": true,
+        "maxNodeModuleJsDepth": 0,
+        "types": ["jest", "node"]
+	},
+    "tsc-alias": {
+        "resolveFullPaths": true,
+        "verbose": false
+    },
+    "include" : ["src/**/*", "test/**/*"]
+}