refactor(types): streamline interface definitions for better readability

[tyler-dane]

claude/cursor's version

• Updated various interface definitions across the codebase to improve formatting and readability by aligning type extensions and removing unnecessary line breaks.
• Adjusted interfaces in event, user, and component types to follow a consistent style, enhancing maintainability and clarity.

Plan

Plan: Server-Driven Auth Classification for Google Reconnect

Problem Statement

After Google Calendar access revocation, re-consent is incorrectly routed through googleSignin() (incremental sync) instead of reconnectGoogleForSession() (full restart sync). This happens because:

• The decision in resolveGoogleSessionUserId() runs before user data is available
• It relies on frontend-provided googleAuthIntent which may not reflect actual server state
• The backend already has authoritative signals (missing refresh token, unhealthy sync) but doesn't use them at the decision point

Proposed Solution

Move auth-path classification server-side using persisted user state, not frontend intent.

Three Auth Modes

Mode	Condition	Handler	Sync Behavior
signup	No linked Compass user	googleSignup()	Full import
signin_incremental	User exists + valid refresh token + healthy sync	googleSignin()	Incremental
reconnect_repair	User exists + (missing refresh token OR unhealthy sync)	repairGoogleConnection()	Full restart

Decision Logic (Pseudocode)

// After OAuth callback + findUserByGoogleId()
function determineAuthMode(user: CompassUser | null, oAuthTokens): AuthMode {
  if (!user) {
    return "signup";
  }

  const hasValidRefreshToken = !!user.google?.gRefreshToken;
  const hasHealthySync = canDoIncrementalSync(user.sync);

  if (!hasValidRefreshToken || !hasHealthySync) {
    return "reconnect_repair";
  }

  return "signin_incremental";
}

Key Files to Modify

Backend

File	Changes
packages/backend/src/auth/services/google/google.auth.success.service.ts	Move decision logic here, after user lookup
packages/backend/src/common/middleware/supertokens.middleware.util.ts	Deprecate resolveGoogleSessionUserId() or simplify to session-only
packages/backend/src/auth/services/compass.auth.service.ts	Rename reconnectGoogleForSession() → repairGoogleConnection(), take compassUserId
packages/backend/src/sync/util/sync.util.ts	Ensure canDoIncrementalSync() returns false after revoke/prune

Frontend (Minimal Changes)

File	Changes
packages/web/src/auth/hooks/oauth/useConnectGoogle.ts	Keep googleAuthIntent as hint (non-authoritative), consider deprecation

.claude/plans/refactored-swimming-whisper.md" 92L, 4489B

Plan: Server-Driven Auth Classification for Google Reconnect

Problem Statement

After Google Calendar access revocation, re-consent is incorrectly routed through googleSignin() (incremental sync) instead of reconnectGoogleForSession() (full restart sync). This happens because:

• The decision in resolveGoogleSessionUserId() runs before user data is available
• It relies on frontend-provided googleAuthIntent which may not reflect actual server state
• The backend already has authoritative signals (missing refresh token, unhealthy sync) but doesn't use them at the decision point

Proposed Solution

Move auth-path classification server-side using persisted user state, not frontend intent.

Three Auth Modes

Mode	Condition	Handler	Sync Behavior
signup	No linked Compass user	googleSignup()	Full import
signin_incremental	User exists + valid refresh token + healthy sync	googleSignin()	Incremental
reconnect_repair	User exists + (missing refresh token OR unhealthy sync)	repairGoogleConnection()	Full restart

Decision Logic (Pseudocode)

// After OAuth callback + findUserByGoogleId()
function determineAuthMode(user: CompassUser | null, oAuthTokens): AuthMode {
  if (!user) {
    return "signup";
  }

  const hasValidRefreshToken = !!user.google?.gRefreshToken;
  const hasHealthySync = canDoIncrementalSync(user.sync);

  if (!hasValidRefreshToken || !hasHealthySync) {
    return "reconnect_repair";
  }

  return "signin_incremental";
}

Key Files to Modify

Backend

File	Changes
packages/backend/src/auth/services/google/google.auth.success.service.ts	Move decision logic here, after user lookup
packages/backend/src/common/middleware/supertokens.middleware.util.ts	Deprecate resolveGoogleSessionUserId() or simplify to session-only
packages/backend/src/auth/services/compass.auth.service.ts	Rename reconnectGoogleForSession() → repairGoogleConnection(), take compassUserId
packages/backend/src/sync/util/sync.util.ts	Ensure canDoIncrementalSync() returns false after revoke/prune

Frontend (Minimal Changes)

File	Changes
packages/web/src/auth/hooks/oauth/useConnectGoogle.ts	Keep googleAuthIntent as hint (non-authoritative), consider deprecation

---

Note

Medium Risk
Changes the Google OAuth success routing and reconnect/repair behavior based on persisted user/sync state, which can affect login and sync restart paths. Risk is mitigated by added unit tests but still touches auth + sync decision logic.

Overview
Moves Google OAuth routing to server-driven auth mode classification. handleGoogleAuth now looks up the Compass user by Google ID, checks stored refresh-token presence and sync health (canDoIncrementalSync), logs the decision, and routes to googleSignup, googleSignin (incremental), or a new repair path.

Replaces session-based reconnect with an explicit repair flow. Renames reconnectGoogleForSession to repairGoogleConnection (takes compassUserId), updates param parsing, and expands tests to cover missing-token/unhealthy-sync/no-sync scenarios.

Tightens incremental-sync eligibility and documents the lifecycle. canDoIncrementalSync now returns false when there are no Google events/calendars, and docs/types mark googleAuthIntent and related middleware helpers as deprecated; remaining PR changes are formatting-only interface/type readability tweaks.

^{Written by Cursor Bugbot for commit 073bfda. This will update automatically on new commits. Configure here.}

[tyler-dane]

@cursoragent Please pick up where I left off by implementing the plan in the issue body and using your best judgement until it's at a satisfactory level

[cursor]

Implementation summary

Core changes

1. Server-side auth mode determination (google.auth.success.service.ts)

   • determineAuthMode() checks user existence, refresh token presence, and sync health
   • handleGoogleAuth() routes based on server-side state
   • Three auth modes: signup, signin_incremental, reconnect_repair

2. Improved canDoIncrementalSync() (sync.util.ts)

   • Handles undefined/empty events arrays
   • Returns false when sync data is missing or incomplete
   • Added JSDoc

3. repairGoogleConnection() method (compass.auth.service.ts)

   • Renamed from reconnectGoogleForSession()
   • Takes compassUserId as first parameter (not session-based)
   • Relinks credentials and restarts sync

4. Deprecated functions (supertokens.middleware.util.ts)

   • resolveGoogleSessionUserId() and getGoogleAuthIntent() marked as deprecated
   • Still pass through for logging but no longer authoritative for routing

Testing

• All backend tests pass (8 tests for handleGoogleAuth)
• Edge cases covered: missing refresh token, unhealthy sync, no sync record, etc.
• Tests verify correct routing for each auth mode

Documentation

• Updated docs/google-sync-and-websocket-flow.md with the new auth flow
• Type definitions include deprecation notices
• JSDoc added to key functions

Status

The implementation follows the plan:

• Auth mode is determined server-side using persisted user state
• Frontend googleAuthIntent is kept as a hint but is non-authoritative
• Reconnect flows correctly route through repairGoogleConnection() when needed
• Edge cases are handled

The code is ready for review and testing. All tests pass, and the changes have been committed and pushed to the refactor/auth-sign-in branch.

  

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Four unused imports left after removing determineAuthMethod
  • Removed the four unused imports (error, getSync, canDoIncrementalSync, findCompassUserBy) that were left behind after determineAuthMethod was removed.