JupiterAPI

JupiterAPI is a Node.js/Express API wrapper for ESN Jupiter data. It exposes normalized endpoints for users, events, statistics, and CSV exports, with optional authenticated write endpoints for Hercules/Firestore workflows.

Why this project exists

Jupiter data is often difficult to consume directly for dashboards, automations, and exports. This service provides:

• Stable JSON endpoints with normalized fields
• Academic-year aware event filtering
• Statistics endpoints for section-level reporting
• Google Contacts CSV export
• Optional JWT-protected write proxy for Hercules data in Firestore

Features

• Express 5 API with API key protection for read endpoints
• AWS Cognito integration for upstream Jupiter authentication
• In-memory caching for Jupiter reads and computed stats
• JWT verification using Cognito JWKS
• Optional role-gated write routes under /hercules

Quick start

npm install
cp .env.example .env
# edit .env with real credentials
npm start

Default server URL: http://localhost:3002

Health check:

curl http://localhost:3002/health

Environment variables

Required for core read API

• AWS_COGNITO_REGION
• AWS_COGNITO_USER_POOL_ID
• AWS_COGNITO_CLIENT_ID
• COGNITO_USERNAME
• COGNITO_PASSWORD
• JUPITER_API_BASE_URL

Required for production hardening

• API_KEY (read API protection)
• ALLOWED_ORIGINS
• RATE_LIMIT_WINDOW_MS
• RATE_LIMIT_MAX_REQUESTS

Optional (advanced / Hercules)

• BOARD_MEMBER_IDS
• GOOGLE_APPLICATION_CREDENTIALS

See .env.example for the full template.

API overview

System

• GET /health
• GET /metrics

Users (API key required)

• GET /users
• GET /users?kind=ERASMUS
• GET /users/search?q=name
• GET /users/:id

Section (API key required)

• GET /section

Events (API key required)

• GET /events
• GET /events?erasmusOnly=false
• GET /events/archived
• GET /events/:id
• GET /events/:id/subscriptions
• GET /events/:id/subscriptions/:userId

National Events (API key required)

• GET /national-events

Registration (API key required)

• GET /requests

Treasury (API key required)

• GET /treasury/cash-flow?since=YYYY-MM-DD&to=YYYY-MM-DD

Statistics (API key required)

• GET /stats/nationality
• GET /stats/field-of-study
• GET /stats/overview
• GET /stats/cities
• GET /stats/comprehensive

Export (API key required)

• GET /export/google-contacts

Auth (no API key required)

• POST /auth/login
• POST /auth/refresh
• POST /auth/verify
• GET /auth/me
• POST /auth/logout

Hercules write API (optional, advanced)

Routes under /hercules/* require:

• Valid Cognito JWT (Authorization: Bearer ...)
• User sub present in BOARD_MEMBER_IDS
• Firebase Admin SDK credentials for Firestore access

Example request

curl -H "X-Api-Key: $API_KEY" "http://localhost:3002/users?kind=ERASMUS"

Security

• Never commit .env, service-account JSON files, or credentials.
• Prefer long random API_KEY values and rotate keys regularly.
• Use immutable Cognito sub IDs for authorization (BOARD_MEMBER_IDS).
• Restrict CORS origins to trusted frontends in production.

If you discover a vulnerability, open a private security report to maintainers instead of a public issue.

Project structure

src/
  index.js              App bootstrap + route mounting
  jupiter.js            Jupiter API client + Cognito auth
  utils.js              Data normalization helpers
  auth.js               Auth routes (/auth/*)
  hercules.js           Write proxy routes (/hercules/*)
  googleContacts.js     CSV export
  middleware/            apiKeyAuth, rateLimiter, jwtAuth, validation
  routes/               One file per domain (users, events, stats, etc.)
docs/
  openapi.yaml          OpenAPI 3.0 spec

Tech stack

• Node.js
• Express
• Axios
• amazon-cognito-identity-js
• jsonwebtoken
• firebase-admin
• csv-stringify

License

MIT