feat: add KYCAS

[ndigvijay]

📌 Description

Re-introduce Know Your Class and Section (KYCAS) data into the PESUAuth API by restoring the old get_know_your_class_and_section() helper, adapted to use the new authenticated PESU Academy endpoint POST /Academy/a/getStudentClassInfo.

The previous public endpoint (/Academy/getStudentClassInfo) was deprecated by PESU Academy and now returns 404. The new endpoint requires an authenticated session (JSESSIONID + CSRF token) that the login step already provides. This PR uses that authenticated session transparently — no additional API parameter or round-trip is needed from the user's perspective.

• Adds know_your_class_and_section boolean parameter back to the authenticate() method (default false)
• Returns KYCAS data under a separate know_your_class_and_section key in the response
• The new endpoint POST /Academy/a/getStudentClassInfo requires controllerMode=370, actionType=174, and loginId=<SRN>, all of which are handled internally
• Field filtering (fields param) applies to both profile and know_your_class_and_section independently, matching the original behavior
• KYCAS fetch failures are non-fatal — they raise KYCASFetchError (HTTP 502) with the same error-handling pattern as other upstream failures

🧱 Type of Change

• ✨ New feature – Adds functionality without breaking existing APIs

🧪 How Has This Been Tested?

• Unit Tests (tests/unit/)
• Functional Tests (tests/functional/)
• Integration Tests (tests/integration/)
• Manual Testing

⚙️ Test Configuration:

• OS: macOS
• Python: 3.14
• Docker build tested

✅ Checklist

• My code follows the CONTRIBUTING.md guidelines
• I've performed a self-review of my changes
• I've added/updated necessary comments and docstrings
• I've updated relevant docs (README or endpoint docs)
• No new warnings introduced
• I've added tests to cover my changes
• All tests pass locally (scripts/run_tests.py)
• I've run linting and formatting (pre-commit run --all-files)
• Docker image builds and runs correctly
• Changes are backwards compatible (if applicable)
• Feature flags or .env vars updated (if applicable)
• I've tested across multiple environments (if applicable)
• Benchmarks still meet expected performance (scripts/benchmark/benchmark_requests.py)

🛠️ Affected API Behaviour

• app/app.py – Modified /authenticate route logic
• app/pesu.py – Updated scraping or authentication handling

🧩 Models

• app/models/request.py – Input validation or request schema changes
• app/models/response.py – Authentication response formatting
• app/models/profile.py – Profile extraction logic
• app/models/kycas.py – New KYCAS response model

🐳 DevOps & Config

• Dockerfile – Changes to base image or build process
• .github/workflows/*.yaml – CI/CD pipeline or deployment updates
• pyproject.toml / requirements.txt – Dependency version changes
• .pre-commit-config.yaml – Linting or formatting hook changes

📊 Benchmarks & Analysis

• scripts/benchmark_auth.py – Performance or latency measurement changes
• scripts/analyze_benchmark.py – Benchmark result analysis changes
• scripts/run_tests.py – Custom test runner logic or behavior updates

📸 Screenshots / API Demos

# Request
curl -X POST http://localhost:5000/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "PESXXUGYYZZZ", "password": "***", "profile": true, "know_your_class_and_section": true}'

# Response (truncated)
{
  "status": true,
  "message": "Login successful.",
  "profile": {
    "name": "John Doe",
    "srn": "PESXXUGYYZZZ",
    ...
  },
  "know_your_class_and_section": {
    "class": "Sem-X",
    "cycle": "NA",
    "department": "Computer Science and Engineering",
    "institute_name": "PES University"
  }
}

🧠 Additional Notes

Implementation details

• The old get_know_your_class_and_section() used BeautifulSoup; the new version uses selectolax.HTMLParser for consistency with the rest of the codebase
• The Pydantic KYCASModel uses validation_alias="class" / serialization_alias="class" because class is a Python reserved keyword, accessed internally as class_field
• model_dump(by_alias=True) was added in app.py to ensure class_field serializes as "class" in JSON output (no-op for ProfileModel since it has no aliases)

Files changed

File	Change
app/exceptions/authentication.py	Added KYCASFetchError (HTTP 502)
app/models/kycas.py	New — Pydantic model for KYCAS response
app/models/__init__.py	Export KYCASModel
app/models/request.py	Added know_your_class_and_section: bool field
app/models/response.py	Added know_your_class_and_section: KYCASModel field
app/pesu.py	Added KYCAS_HEADER_TO_KEY_MAP, get_know_your_class_and_section() method, know_your_class_and_section param on authenticate(), updated DEFAULT_FIELDS
app/app.py	Pass new param from request, by_alias=True in model_dump
app/docs/authenticate.py	Added KYCAS request/response examples