feat(api): expose whether sessions have a maximum lifetime

[swolfand]

What & why

Add Session.hasMaximumLifetime so callers can distinguish indefinite native sessions from finite expiration deadlines. Cover zero-deadline serialization and keep session status separate from lifetime.

Companion to the backend native-session policy, clerk_go#22459 → #22460 → #22461 → #22462 → #22369. Part of MOBILE-517.

Other companions: iOS, JavaScript/Expo, Dashboard, edge regression tests, docs.

What to focus on

expireAt == 0 means no maximum lifetime, including when a session is revoked.

expireAt stays a required Long. The backend always sends expire_at as a number, 0 for sessions without a maximum lifetime, never omitted or null: the client and server session serializers in api/serialize/session.go declare it as a plain int64 without omitempty and fill it with UnixMilliOrZero (clerk_go#22459).

Nothing in the SDK compares Session.expireAt against the current time, so a zero deadline is never treated as expired. Token refresh uses the session token's own expiry.

Screenshots / video

No UI changes.

Summary by CodeRabbit

• New Features
  • Sessions now indicate whether they have a maximum lifetime.
  • Session expiration information distinguishes the maximum-lifetime deadline from the inactivity deadline; a value of zero indicates that the corresponding deadline is not set.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: clerk/clerk-android/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: 719d222e-772a-476a-911d-41892d83eb6b

📥 Commits

Reviewing files that changed from the base of the PR and between 75cfc90 and 5d9d1ff.

📒 Files selected for processing: 3

• source/api/api/api.api
• source/api/src/main/kotlin/com/clerk/api/session/Session.kt
• source/api/src/test/java/com/clerk/api/session/SessionLifetimeTest.kt

Included review availability: This review used your included allowance. 9 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

📝 Walkthrough

Session documents expireAt and abandonAt as maximum-lifetime and inactivity deadlines. It adds hasMaximumLifetime, which is true when expireAt is greater than zero. Tests cover this property, zero-deadline decoding, and serialization.

Changes: Session lifetime

Layer / File(s)	Summary
Define and validate the maximum lifetime property source/api/src/main/kotlin/com/clerk/api/session/Session.kt, source/api/api/api.api, source/api/src/test/java/com/clerk/api/session/SessionLifetimeTest.kt	Session documents the meaning of its deadline fields and adds hasMaximumLifetime. The API declaration exposes its accessor. Tests cover zero and future expire_at values, decoding zero deadlines, and serialization of an indefinite session.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: seanperez29

Merge Risk: ⚪ Minimal · up to 5d9d1

No actionable merge-blocking issue is evident from the supplied changes; this is ready for normal merge checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: exposing whether sessions have a maximum lifetime.
Description check		The description includes the required What & why, What to focus on, and Screenshots / video sections. It explains the purpose, backend deadline behavior, review focus, and confirms that there are no U…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 2

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[swolfand]

• Won't build on main: explicitApi() is on since build: enable explicit API mode for api, ui and telemetry #1023, and val hasMaximumLifetime (Session.kt:67) has no public modifier.
• source/api/api/api.api isn't updated, so apiCheck fails.
• Conflicts in Session.kt (chore: remove comments that restate code #977 removed the abandon_at comment); consider moving that note to KDoc.
• expireAt is still a required Long. If the backend omits expire_at for indefinite sessions rather than sending 0, decoding fails; confirm or default it.
• SessionLifetimeTest asserts seven unrelated things in one test; split it.