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 (zero business logic)
  config.js             Sole env reader; fail-fast validation
  jupiter.js            Jupiter API client + Cognito auth + caches
  googleContacts.js     Google Contacts CSV building/streaming
  normalizers.js        User/event/subscription normalization
  formatting.js         Date/phone/academic-year helpers
  nationality.js        Nationality + country-code mapping
  fieldsOfStudy.js      Field labels + UniMore campus mapping
  eventLocation.js      Modena/Reggio Emilia inference rules
  middleware/           apiKeyAuth, rateLimiter, jwtAuth, validation, asyncHandler
  routes/               One file per URL prefix (users, events, stats, auth, hercules, ...)
test/
  unit/                 Characterization tests for pure modules
  routes/               HTTP suites with mocked Jupiter/Cognito/Firestore
  helpers/              mockModule, fixtures, cognitoStub, fakeFirestore
docs/
  openapi.yaml          OpenAPI 3.0 spec
  ARCHITECTURE.md       Domains, dependency direction, flows, decisions
  FEATURES.md           Feature-to-module map with test pointers

Documentation

• AGENTS.md — repo map and architectural rules for humans and AI agents
• docs/ARCHITECTURE.md — how the pieces fit together
• docs/FEATURES.md — every feature, its owner module, and its tests
• docs/openapi.yaml — API reference

Tech stack

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

License

MIT