DOCSEARCHbyAlgolia
Submit Docs

Ham Documentation

website·Indexed 31 days ago

https://docs.ham.nowcent.cn

Documentation for Ham, a campus utility tool featuring course and grade management, library and sports facility booking, and real-time campus bus information. Includes developer resources 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
16.1K
Snippets
44
Records
129
Agent score
53%

What's inside Ham

  1. Overview of Ham Web

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

    • SSO Authorization: Handling OAuth2 authorization flows, including login and consent confirmation.
    • Web Console: Managing API Keys and account information (available at ham.nowcent.cn/console).
    • Authentication Methods: Supporting QR code login via the Ham app and passwordless login via WebAuthn/Passkeys.
    • Mobile H5 Fallback: Providing a web-based install prompt and Passkey login for users without the native app.

  2. Overview of Ham 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 retrieve user information from the Ham Resource Server.
    flowchart LR
    RO["Resource Owner<br/>(Ham User)"]
    C["Third-party App<br/>(Client)"]
    AUI["Ham<br/>(Authorization UI)"]
    AS["Ham Open Platform<br/>open-api.ham.nowcent.cn"]

    C -- "1. Universal Link<br/>https://ham.nowcent.cn/sso-authorize" --> AUI
    AUI -- "2. User approves" --> RO
    AUI -- "3. Redirect redirect_uri + code" --> C
    C -- "4. POST /oauth/token" --> AS
    AS -- "5. Return access_token" --> C
    C -- "6. GET /oauth/userinfo" --> AS
    AS -- "7. Return open_id / nickname / ..." --> C

  3. Overview of Ham Connect SSO

    Ham Connect is an OAuth 2.0 authorization service (based on the Authorization Code Grant flow, RFC 6749 §4.1) that allows third-party applications to securely obtain authorized Ham user information. It enables 'Sign in with Ham' functionality.

  4. Overview of Ham developer projects

    The Ham developer ecosystem consists of three primary projects:

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

  5. Overview of Ham Guide and MCP Service

    The Ham Guide provides comprehensive documentation for using Ham's features and integrating its data into AI assistants. It is divided into two primary sections: the Handbook, which covers usage instructions for courses, grades, library, and sports facilities; and the MCP Service documentation, which details how to integrate Ham's capabilities via the Model Context Protocol (MCP).

  6. Understand Ham's security and data privacy model

    Ham prioritizes local data storage and direct connections to university servers. Student accounts and passwords are not sent to third-party servers for validation. For features requiring a backend service (such as grade distribution), data is only transmitted with user consent, and sensitive identifiers like student IDs are hashed before transmission to ensure individual users cannot be identified.

  7. 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 and consent views), and console/ (account and API key management).
    • components/: Shared UI components like LanguageSwitcher, ThemeSwitcher, and SearchBar.
    • i18n/: Configuration for next-intl.
    • messages/: Locale catalogs (en.json, zh.json, ja.json).
    • services/: API and service layer logic.
    • store/: State management for locale and theme.
    • public/: Static assets.

  8. 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

  9. Score Calculator Module architecture and workflow

    The Score Calculator module consists of business logic for fetching scripts (business/education/scorecalc) and UI components for selection (components/scorecalc).

    Workflow:

    1. User navigates to: Me → Scores → Settings → Use other calculation (JavaScript-based) → Choose calculation.
    2. The RNScoreCalcView component loads and retrieves the current script via NativeScoreCalcModule.getCurrentCalc.
    3. Available scripts are fetched from remote sources (e.g., GitHub).
    4. When a user selects a script, it is tested via NativeScoreCalcModule.testItem and applied via NativeScoreCalcModule.selectCalc.
    5. The native app then recalculates the GPA using the selected script.

  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 others) to securely query course information, grades, and personal information. The service uses Streamable HTTP transport.
    Service URL: https://mcp.ham.nowcent.cn/mcp

  12. Implement CAS authentication for WHU information portal

    The CAS (Central Authentication Service) module provides a unified identity authentication system for the university. It functions by loading the CAS login page in a WebView, injecting JavaScript for form localization, intercepting the authentication cookies upon success, and passing those cookies to the native side for use in subsequent education system requests (e.g., course or grade queries).