feat: add Impersonation component

[nicknisi]

Summary

Port the Impersonation component from authkit-nextjs to provide a built-in admin banner when a WorkOS admin is impersonating a user. The component is framework-agnostic (plain React + CSS variables) and wires into the existing useAuth() hook and server function patterns.

• Add Impersonation, Button, and MinMaxButton components to @workos/authkit-tanstack-react-start/client
• Add getOrganizationAction server function to fetch org details for the impersonation banner
• Add CSS custom property type augmentation for React's style prop
• Add example usage in the example app's root layout
• 15 unit tests covering rendering, org fetching, sign-out, positioning, style merging, and caching

Usage

import { AuthKitProvider, Impersonation } from '@workos/authkit-tanstack-react-start/client';

function RootComponent() {
  return (
    <AuthKitProvider>
      {/* your app */}
      <Impersonation />
    </AuthKitProvider>
  );
}

The component renders nothing when no impersonation is active. When a WorkOS admin impersonates a user, it displays a fixed banner with the impersonated user's email, organization name, and a "Stop" button.

Props

Prop	Type	Default	Description
side	'top' | 'bottom'	'bottom'	Banner position
returnTo	string	undefined	Redirect URL after stopping impersonation

Theming via CSS variables

Variable	Default
--workos-impersonation-size	4px
--workos-impersonation-background-color	#fce654
--workos-impersonation-color	#1a1600
--workos-impersonation-border-color	#e0c36c
--workos-impersonation-border-width	1px

[greptile-apps]

Greptile Summary

This PR ports the Impersonation component from authkit-nextjs, providing an admin banner for WorkOS impersonation sessions. The implementation is clean and well-tested with 15 unit tests.

Key Changes:

• Added Impersonation, Button, and MinMaxButton components with CSS variable-based theming
• Added getOrganizationAction server function to fetch organization details
• Added CSS custom property type augmentation for React
• Comprehensive test coverage for rendering, org fetching, positioning, and edge cases

Issues Found:

• Missing error handling in getOrganizationAction call (client-side) and server function - errors are silently ignored
• Previous review flagged missing organization dependency in useEffect array causing stale closure (already documented in previous thread)

The component architecture is solid, integrating seamlessly with existing useAuth() patterns. The CSS-in-JS approach with custom properties provides good theming flexibility.

Confidence Score: 4/5

• This PR is generally safe to merge with minor error handling improvements recommended
• Score reflects well-structured code with comprehensive tests, but missing error handling could cause silent failures when fetching organization details
• Pay close attention to src/client/components/impersonation.tsx and src/server/actions.ts for error handling improvements

Important Files Changed

Filename	Overview
src/client/components/impersonation.tsx	Main impersonation component with missing error handling for org fetch and stale closure issue in useEffect
src/server/actions.ts	Adds getOrganizationAction server function with no error handling for failed org lookups
src/client/impersonation.spec.tsx	Comprehensive test suite with 15 tests covering rendering, org fetching, sign-out, and edge cases

Sequence Diagram

sequenceDiagram
    participant User
    participant Impersonation
    participant useAuth
    participant getOrganizationAction
    participant WorkOS
    
    User->>Impersonation: Render component
    Impersonation->>useAuth: Get auth state
    useAuth-->>Impersonation: user, impersonator, organizationId
    
    alt No impersonation active
        Impersonation-->>User: Render null
    else Impersonation active
        Impersonation-->>User: Render banner with user email
        
        alt organizationId exists
            Impersonation->>getOrganizationAction: Fetch organization details
            getOrganizationAction->>WorkOS: Get organization by ID
            WorkOS-->>getOrganizationAction: Organization data
            getOrganizationAction-->>Impersonation: OrganizationInfo
            Impersonation-->>User: Update banner with org name
        end
        
        User->>Impersonation: Click Stop button
        Impersonation->>useAuth: Call signOut with returnTo
        useAuth-->>User: Redirect to sign out
    end

Loading

_{Last reviewed commit: c78646f}

[greptile-apps]

_{9 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[nicknisi]

@greptileai

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}