API guide

Call campus authentication flows from Java code.

The public Java surface is intentionally small. `AuthService` performs the work, `AuthMethod` selects strategies, and response objects preserve enough detail to distinguish authentication results from service failures.

Entrypoints

Use fallback mode when you want the library to choose the first method that can answer definitively. Use the method-specific overload when your application needs a particular campus service flow.

import campus.auth.java.AuthMethod;
import campus.auth.java.AuthResponse;
import campus.auth.java.AuthResult;
import campus.auth.java.AuthService;

AuthResult result = AuthService.authenticate("student_id", "password");

AuthResponse portal = AuthService.authenticate(
    "student_id",
    "password",
    AuthMethod.PORTAL_SSO_TOKEN
);

Response model

The response model is designed for branch-safe application code. A request can fail, an upstream page can change, or an authenticator can be unable to decide. Those states should be handled separately.

Field	Type	Use it for
`success`	boolean	Whether the service interaction produced a usable response.
`is_auth`	boolean or null	The credential decision when known. Null means unknown, not false.
`status_code`	integer or null	HTTP result when available. Timeout and local failures can be null.
`code`	string	Machine-readable branch key for application logic and logs.
`body`	object	Messages or metadata extracted by the successful method.
`authenticator`	string	The method that produced the final result.

Recommended handling

Applications should avoid flattening every result into one boolean. That makes outages look like invalid passwords and creates confusing user experiences.

AuthResult result = AuthService.authenticate(id, password);

if (!result.getSuccess()) {
    // Service or parsing failure. Retry, fallback, or show unknown state.
} else if (Boolean.TRUE.equals(result.getIsAuth())) {
    // Authenticated.
} else if (Boolean.FALSE.equals(result.getIsAuth())) {
    // Definite credential failure.
} else {
    // Unknown result.
}

Extension points

New authenticators should implement the shared `Authenticator` contract, use explicit timeouts, avoid logging secrets, and return stable result codes. The implementation should treat unexpected DOM changes as unknown or parse failures instead of guessing that credentials are invalid.

Safety default: when an authenticator cannot prove the credential decision, return an unknown or failure state and let the caller decide whether to retry or fall back.