DOCSEARCHbyAlgolia
Submit Docs

Ham Documentation

website·Indexed 29 days ago

https://whu-ham.github.io/

Documentation for Ham, a campus utility tool featuring course and grade management, library and sports facility booking, and real-time campus bus information. Includes a developer portal for Ham Connect SSO via OAuth2, a React Native component library, and an MCP service to connect Ham's capabilities to AI assistants like Claude and ChatGPT.

Tokens
15.4K
Snippets
42
Records
124
Agent score
75%

What's inside Ham

  1. Overview of Ham developer projects

    The Ham developer ecosystem consists of three main projects:

    1. Ham Connect: An OAuth 2.0 authorization service for the Ham open platform. It enables third-party applications to implement "Sign in with Ham" functionality and securely obtain user authorization.
    2. Ham Web: A Next.js-based web frontend that manages the SSO (Single Sign-On) authorization flow, including Passkey and QR code login. It serves as the web entry point for Ham Connect.
    3. Ham React Native Components: A repository of React Native components integrated into native apps via Over-the-Air (OTA) hot updates. This project manages UI and business logic for core features like CAS authentication, GPA calculation, grade queries, and course schedule queries.

  2. Overview of Ham Web frontend

    Ham Web is the web frontend for the Ham Connect platform. It serves as the primary web entry point and is used for the following core functions:

    • SSO Authorization: Handles OAuth2 authorization flows, including login and consent confirmation for third-party apps.
    • Web Console: Provides a browser-based interface for managing API Keys and account information (available at ham.nowcent.cn/console).
    • Authentication Methods: Supports QR code login (via the Ham app) and WebAuthn/Passkey passwordless login.
    • Mobile H5 Fallback: Provides a web-based install prompt and Passkey login for users without the native app.

  3. Overview of Ham Guide and MCP Service

    The Ham Guide provides two primary resources for users: the Handbook, which contains usage instructions for features such as courses, grades, library, and sports facilities, and the MCP (Model Context Protocol) service documentation, which explains how to integrate Ham's data and capabilities into AI assistants.

  4. Overview of Ham Connect OAuth 2.0 Integration

    Ham Connect is an OAuth 2.0 authorization service based on the Authorization Code Grant (RFC 6749 §4.1). It allows third-party applications to securely obtain authorized Ham user information. The flow involves launching Ham via a Universal Link, receiving an authorization code, exchanging that code for an access token, and finally fetching user information.

  5. Overview of Ham Open Platform OAuth 2.0 Integration

    The Ham Open Platform uses the OAuth 2.0 Authorization Code Grant (RFC 6749 §4.1) for SSO. Third-party applications (Clients) initiate authorization requests to Ham, receive a short-lived authorization code, and exchange it for an access token to fetch user information.

    Key Endpoints:

    • Open Platform API Domain: https://open-api.ham.nowcent.cn (All server-to-server calls, HTTPS enforced)
    • Authorization Entry (Universal Link): https://ham.nowcent.cn/sso-authorize

  6. Implement CAS authentication for WHU information portal

    The CAS (Central Authentication Service) module provides a unified identity authentication system for the Ham app. It functions by loading the university's CAS login page in a WebView, injecting JavaScript for multi-language localization, and intercepting the resulting session cookies to be used for subsequent education system requests (e.g., course or grade queries).

  7. Use the Status page for daily task and schedule tracking

    The Status page serves as a central dashboard for managing daily activities. It provides real-time information and quick access to the following features:

    • Weather: Real-time weather updates for clothing adjustments.
    • Library Reservation: View current reservations and quickly modify reservation times.
    • Classes: View course schedules for the current and following day.
    • Schedule: Access custom schedule items added within the Ham application.
    • Campus Bus: View bus information for the nearest stop.
    • Sports: View details of booked sports venues.

  9. Install and run Ham React Native Components

    To set up the Ham React Native development environment, ensure you have Node.js >= 18, pnpm, Xcode (for iOS), Android Studio (for Android), and CocoaPods installed. The project uses React Native 0.83 (New Architecture) and pnpm as the package manager.
    # Install dependencies
pnpm install

# iOS additional setup
cd ios && pod install && cd ..

# Start Metro bundler
pnpm start

# Run on iOS
pnpm ios

# Run on Android
pnpm android

  10. Configure OTA updates and locale syncing with RNCommon

    The RNCommon component is an invisible background component loaded at app startup. It performs two critical initialization tasks:

    1. Initializes the hot-updater OTA (Over-The-Air) hot update listener.
    2. Listens for native locale change events to synchronize the i18next language settings.

  11. Connect Ham campus data to AI assistants via MCP

    Ham provides a Model Context Protocol (MCP) service that enables MCP-compatible AI assistants (such as Claude Desktop, Cursor, and ChatGPT) to securely query course information, grades, and personal data. The service uses Streamable HTTP transport.
    Service URL: https://mcp.ham.nowcent.cn/mcp

  12. Ham Web project structure

    The project follows a Next.js App Router architecture:

    • app/: Entry point containing api/ (auth and sso routes), sso-authorize/ (login/consent views), and console/ (account/API key management).
    • components/: Shared UI components like LanguageSwitcher, ThemeSwitcher, and SearchBar.
    • i18n/: Runtime configuration for next-intl.
    • messages/: Locale catalogs (en.json, zh.json, ja.json).
    • services/: API and service layer logic.
    • store/: State management for theme and locale.
    • public/: Static assets.