@graymattersalliance/session-countdown

@graymattersalliance/session-countdown

Idle-session countdown for CompassCare web apps: 30 minutes of inactivity, visible clock, red warning in the last 5 minutes, cross-tab sync, and one endSession() path for teardown + replace-navigation.

Same publishing shape as @graymattersalliance/cognitoauthkit (GMA-TECH private repo → public npm scope). Package exports follow the @compass/ui pattern (exports map, peerDependencies, no bundled React).

Extracted from GMA-TECH/react-app GMA-1909 (#537). Tracking: react-app #551.

Install

npm install @graymattersalliance/session-countdown

Peer deps: react and react-dom (^17 or ^18).

Quick start

import {
  SessionCountdownProvider,
  SessionCountdownBadge,
  SessionCountdownSlot,
  onSessionEnd,
  emitSessionEndAndSettle,
  markIdleLogout,
  consumeIdleLogoutNotice,
} from '@graymattersalliance/session-countdown';

function AuthRoot({ children, isAuthenticated, logout }) {
  return (
    <SessionCountdownProvider
      enabled={isAuthenticated}
      onExpire={async () => {
        await logout(); // clear credentials
        window.location.replace('/login'); // REPLACE, never push
      }}
      onTelemetry={(event, data) => addBreadcrumb(event, data)}
      emitSessionEnd={emitSessionEndAndSettle}
      navigateToLogin={() => window.location.replace('/login')}
    >
      {children}
      <SessionCountdownBadge />
    </SessionCountdownProvider>
  );
}

// In a shell header (optional — badge floats when no slot exists):
function Header() {
  return (
    <header>
      <SessionCountdownSlot />
      {/* other controls */}
    </header>
  );
}

// Surfaces that must tear down on sign-out (e.g. live call):
useEffect(() => onSessionEnd(() => endLiveCall()), []);

Invariants (do not break)

• One deadline — mount the provider once; never two engines.
• replace, not push on every session-end navigation — a pushed history entry can restore an unguarded route (e.g. /call) after sign-out.
• Countdown never issues authenticated requests — that would keep the session alive.
• Expired stored deadlines are adopted, never overwritten.
• Activity / reset past the deadline does not extend it.

API surface

Publish

# from packages/session-countdown, with NPM_TOKEN set
npm publish

Uses the same .npmrc token pattern as CognitoAuthKit.