SDK and registration questions

.github/workflows/build.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

.github/workflows/production.yml

@@ -19,7 +19,7 @@ jobs:
       IMAGE_NAME: us-east4-docker.pkg.dev/${{ secrets.GCP_PROJECT_ID }}/api-v3/${{ secrets.GCP_PRODUCTION_SERVICE_NAME }}:${{ github.sha }}
     steps:
     - name: Checkout
-      uses: actions/checkout@v5.0.0
+      uses: actions/checkout@v6.0.1
 
     - id: 'auth'
       name: Authenticate to Google Cloud

.github/workflows/staging.yml

@@ -19,7 +19,7 @@ jobs:
       IMAGE_NAME: us-east4-docker.pkg.dev/${{ secrets.GCP_PROJECT_ID }}/api-v3/${{ secrets.GCP_STAGING_SERVICE_NAME }}:${{ github.sha }}
     steps:
     - name: Checkout
-      uses: actions/checkout@v5.0.0
+      uses: actions/checkout@v6.0.1
 
     - id: 'auth'
       name: Authenticate to Google Cloud

.gitignore

@@ -53,4 +53,8 @@ cloud-sql-proxy
 .yarn/*
 
 # Cert
-certs/*
+certs/*
+
+# SDK Artifacts
+sdk/node_modules/
+sdk/dist/

db/migrations/20251204204114_add_registration_questions.ts

@@ -0,0 +1,24 @@
+import type { Knex } from "knex";
+
+
+export async function up(knex: Knex): Promise<void> {
+    await knex.schema.alterTable("registrations", (table) => {
+        table.string("excitement").nullable();
+        table.string("zip_code").nullable();
+        table.integer("travel_cost").nullable();
+        table.string("travel_method").nullable();
+        table.string("travel_additional").nullable();
+    });
+}
+
+
+export async function down(knex: Knex): Promise<void> {
+    await knex.schema.alterTable("registrations", (table) => {
+        table.dropColumn("excitement");
+        table.dropColumn("zip_code");
+        table.dropColumn("travel_cost");
+        table.dropColumn("travel_method");
+        table.dropColumn("travel_additional");
+    });
+}
+

package.json

@@ -40,7 +40,7 @@
     "fast-xml-parser": "^5.2.3",
     "firebase": "^12.0.0",
     "firebase-admin": "^13.0.2",
-    "googleapis": "^164.0.0",
+    "googleapis": "^167.0.0",
     "handlebars": "^4.7.8",
     "jsonwebtoken": "^9.0.2",
     "jwt-decode": "^4.0.0",
@@ -79,7 +79,7 @@
     "@types/luxon": "^3.4.2",
     "@types/mock-knex": "^0.4.8",
     "@types/multer": "^2.0.0",
-    "@types/node": "^22.10.5",
+    "@types/node": "^24.0.0",
     "@types/passport-jwt": "^4.0.1",
     "@types/sharp": "^0.32.0",
     "@types/supertest": "^6.0.2",
@@ -94,7 +94,7 @@
     "rimraf": "^6.0.1",
     "source-map-support": "^0.5.21",
     "supertest": "^7.0.0",
-    "ts-jest": "29.4.5",
+    "ts-jest": "29.4.6",
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",

sdk/.npmignore

@@ -0,0 +1,15 @@
+# Source files (only publish dist/)
+**/*.ts
+**/*.tsx
+!**/*.d.ts
+
+# Config files
+tsconfig.json
+tsup.config.ts
+
+# Development files
+node_modules/
+*.log
+.DS_Store
+
+# Only publish the dist folder and package files

sdk/README.md

@@ -0,0 +1,200 @@
+# @hackpsu/react-sdk
+
+Shared React hooks, providers, and API clients for HackPSU projects. This package provides a consistent way to interact with the HackPSU API, manage authentication with Firebase, and share common UI patterns across all HackPSU web applications.
+
+## Installation
+
+```bash
+npm install @hackpsu/react-sdk
+```
+
+## Required Environment Variables
+
+All projects using this SDK need these environment variables in your `.env.local` or `.env` file:
+
+```env
+# Firebase Configuration
+NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
+NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
+NEXT_PUBLIC_FIREBASE_DATABASE_URL=your_database_url
+NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
+NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
+NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
+NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
+
+# API Configuration
+NEXT_PUBLIC_BASE_URL_V3=https://api.hackpsu.org/v3
+NEXT_PUBLIC_AUTH_SERVICE_URL=https://auth.hackpsu.org
+```
+
+## Usage
+
+### 1. Setup Providers
+
+Wrap your application with the `LayoutProvider` to get Firebase authentication, React Query, and auth guards:
+
+```tsx
+// app/layout.tsx or pages/_app.tsx
+import { LayoutProvider } from '@hackpsu/react-sdk/context';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <LayoutProvider>{children}</LayoutProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 2. Use Authentication
+
+Access Firebase auth state using the `useFirebase` hook:
+
+```tsx
+import { useFirebase } from '@hackpsu/react-sdk/context';
+
+export default function ProfilePage() {
+  const { user, isLoading, logout } = useFirebase();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!user) return <div>Not authenticated</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user.email}</h1>
+      <button onClick={logout}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### 3. Use API Hooks
+
+The SDK provides React Query hooks for all API endpoints:
+
+```tsx
+import { useAllRegistrations, useCreateRegistration } from '@hackpsu/react-sdk/api/registration';
+
+export default function RegistrationsPage() {
+  const { data: registrations, isLoading } = useAllRegistrations();
+  const createMutation = useCreateRegistration();
+
+  const handleCreate = async () => {
+    await createMutation.mutateAsync({
+      // registration data
+    });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {registrations?.map(reg => (
+        <div key={reg.id}>{reg.name}</div>
+      ))}
+      <button onClick={handleCreate}>Create Registration</button>
+    </div>
+  );
+}
+```
+
+### 4. Custom Auth Guard
+
+You can also use the `AuthGuard` component directly with custom role requirements:
+
+```tsx
+import { AuthGuard, Role } from '@hackpsu/react-sdk/context';
+
+export default function AdminPage() {
+  return (
+    <AuthGuard config={{ minimumRole: Role.EXEC }}>
+      <div>Admin content - only visible to executives</div>
+    </AuthGuard>
+  );
+}
+```
+
+## Available Modules
+
+### Context
+
+- `FirebaseProvider` - Firebase authentication context
+- `useFirebase` - Hook to access Firebase auth state
+- `LayoutProvider` - Complete layout setup with Firebase, React Query, and auth
+- `AuthGuard` - Component to protect routes with role-based access
+- `Role` - Enum for role levels
+
+### Config
+
+- `auth` - Initialized Firebase auth instance
+- `getEnvironment` - Function to get environment configuration
+
+### API Modules
+
+Each API module exports:
+- Entity types (TypeScript interfaces)
+- Provider functions (raw API calls)
+- React Query hooks (useQuery/useMutation)
+
+Available modules:
+- `api/analytics`
+- `api/event`
+- `api/extra-credit`
+- `api/finance`
+- `api/flag`
+- `api/hackathon`
+- `api/judging`
+- `api/location`
+- `api/organizer`
+- `api/photos`
+- `api/registration`
+- `api/reservation`
+- `api/scan`
+- `api/sponsor`
+- `api/team`
+- `api/user`
+- `api/wallet`
+
+## Examples
+
+### Import specific modules
+
+```tsx
+// Import from specific subpaths
+import { useFirebase } from '@hackpsu/react-sdk/context';
+import { auth } from '@hackpsu/react-sdk/config';
+import { useAllEvents } from '@hackpsu/react-sdk/api/event';
+```
+
+### Import everything (not recommended for production)
+
+```tsx
+// Import everything at once (larger bundle size)
+import { useFirebase, useAllEvents, auth } from '@hackpsu/react-sdk';
+```
+
+## Development
+
+To build the package:
+
+```bash
+cd lib
+npm install
+npm run build
+```
+
+## Publishing
+
+This package is published to npm under the `@hackpsu` organization:
+
+```bash
+cd lib
+npm version patch  # or minor, or major
+npm publish
+```
+
+## License
+
+MIT

sdk/api/analytics/entity.ts

@@ -0,0 +1,46 @@
+export interface CountsResponse {
+	count: number;
+}
+
+export interface RegistrationCounts extends CountsResponse {
+	id: string;
+	name: string;
+}
+
+export interface GenderCounts extends CountsResponse {
+	gender: string;
+}
+
+export interface RaceCounts extends CountsResponse {
+	race: string;
+}
+
+export interface AcademicYearCounts extends CountsResponse {
+	academicYear: string;
+}
+
+export interface CodingExpCounts extends CountsResponse {
+	codingExperience: string;
+}
+
+export interface AnalyticsSummaryResponse {
+	registrations: RegistrationCounts[];
+	gender: GenderCounts[];
+	race: RaceCounts[];
+	academicYear: AcademicYearCounts[];
+	codingExp: CodingExpCounts[];
+}
+
+export interface AnalyticsScansResponse {
+	id: string;
+	firstName: string;
+	lastName: string;
+	count: number;
+}
+
+export interface AnalyticsEventsResponse {
+	type: string;
+	id: string;
+	name: string;
+	count: number;
+}

sdk/api/analytics/hook.ts

@@ -0,0 +1,38 @@
+import { useQuery } from "@tanstack/react-query";
+import {
+	getAnalyticsSummary,
+	getEventsAnalytics,
+	getOrganizerScans,
+} from "./provider";
+import {
+	AnalyticsSummaryResponse,
+	AnalyticsEventsResponse,
+	AnalyticsScansResponse,
+} from "./entity";
+
+export const analyticsQueryKeys = {
+	summary: ["analytics", "summary"] as const,
+	events: ["analytics", "events"] as const,
+	scans: ["analytics", "scans"] as const,
+};
+
+export function useAnalyticsSummary() {
+	return useQuery<AnalyticsSummaryResponse>({
+		queryKey: analyticsQueryKeys.summary,
+		queryFn: getAnalyticsSummary,
+	});
+}
+
+export function useEventsAnalytics() {
+	return useQuery<AnalyticsEventsResponse[]>({
+		queryKey: analyticsQueryKeys.events,
+		queryFn: getEventsAnalytics,
+	});
+}
+
+export function useOrganizerScans() {
+	return useQuery<AnalyticsScansResponse[]>({
+		queryKey: analyticsQueryKeys.scans,
+		queryFn: getOrganizerScans,
+	});
+}

sdk/api/analytics/index.ts

@@ -0,0 +1,3 @@
+export * from "./entity";
+export * from "./provider";
+export * from "./hook";