feat: enable enterprise team metrics via Enterprise Teams API (#348)

* feat: enable enterprise team metrics via Enterprise Teams API

- Update enterprise team members endpoint to /memberships (new API)
- Add X-GitHub-Api-Version: 2026-03-10 header for enterprise teams/members
- Add team-scoped direct API path in metrics-util-v2 (no DB required)
- Make teams tab always visible (remove historical mode restriction)
- Add defensive response normalization for enterprise team members
- Improve aggregateTeamMetrics to use case-insensitive login matching
- Add tests for enterprise team members URL and case-insensitive matching

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* add rate limit warning banner on teams tab when not using historical mode

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: abhi-singhs

app/components/TeamsComponent.vue

@@ -12,6 +12,20 @@
       </div>
     </v-card>
 
+    <!-- Rate limit warning when not using historical/DB mode -->
+    <v-alert
+      v-if="!isHistoricalMode"
+      type="warning"
+      variant="tonal"
+      density="compact"
+      class="mx-4 mb-1"
+      closable
+    >
+      <strong>Performance notice:</strong> Team metrics are computed by fetching enterprise-wide user data and filtering by team membership.
+      Each team selection triggers a full user-metrics download, which may hit GitHub API rate limits with frequent use.
+      For production use, enable <strong>historical mode</strong> (<code>ENABLE_HISTORICAL_MODE=true</code>) to cache data in the database and avoid repeated API calls.
+    </v-alert>
+
     <!-- Team selector -->
     <v-card variant="outlined" class="mx-4 mb-2 pa-3" density="compact">
       <div class="d-flex align-center gap-2">
@@ -475,6 +489,10 @@ export default defineComponent({
   setup(props) {
     const theme = useTheme()
     const isDark = computed(() => theme.global.current.value.dark)
+    const config = useRuntimeConfig()
+    const isHistoricalMode = computed(() =>
+      config.public?.enableHistoricalMode === true || config.public?.enableHistoricalMode === 'true'
+    )
 
     const availableTeams = ref<Team[]>([])
     const selectedTeams = ref<string[]>([])
@@ -1071,6 +1089,7 @@ export default defineComponent({
       clearSelection,
       getTeamDetailUrl,
       isDark,
+      isHistoricalMode,
       dateRangeDesc: props.dateRangeDescription
     }
   }

app/model/Options.ts

@@ -370,7 +370,7 @@ export class Options {
                 if (!this.githubEnt || !this.githubTeam) {
                     throw new Error('GitHub enterprise and team must be set for enterprise scope');
                 }
-                return `${baseUrl}/enterprises/${this.githubEnt}/teams/${this.githubTeam}/members`;
+                return `${baseUrl}/enterprises/${this.githubEnt}/teams/${this.githubTeam}/memberships`;
 
             default:
                 throw new Error(`Invalid scope: ${this.scope}`);

app/utils/tabUtils.ts

@@ -10,14 +10,15 @@ export function applyHiddenTabs(tabItems: string[], hiddenTabsConfig: string): s
 }
 
 /**
- * Auto-hides the "teams" tab when historical mode is disabled.
- * Team metrics require the user_day_metrics DB table; without it the teams
- * tab falls back to org-wide data and shows identical (incorrect) data for every team.
+ * Historical mode filter — previously hid the "teams" tab when historical
+ * mode was disabled (team metrics required the user_day_metrics DB table).
+ *
+ * Team metrics now work in direct API mode (by fetching enterprise/org
+ * user-level records and filtering by team membership), so the teams tab
+ * is always visible regardless of historical mode.
+ *
+ * Kept for backward compatibility; callers don't need to change.
  */
-export function applyHistoricalModeFilter(tabItems: string[], enableHistoricalMode: boolean | string): string[] {
-    const historicalMode = enableHistoricalMode === true || enableHistoricalMode === 'true'
-    if (!historicalMode && tabItems.includes('teams')) {
-        return tabItems.filter((t: string) => t !== 'teams')
-    }
-    return tabItems
+export function applyHistoricalModeFilter(tabItems: string[], _enableHistoricalMode: boolean | string): string[] {
+    return tabItems;
 }

server/api/seats.ts

@@ -29,17 +29,15 @@ export interface TeamMember {
 }
 
 /**
- * Fetch all members of a team (org team scope) handling GitHub API pagination.
- * For now this is limited to organization team scopes. Enterprise team member
- * listing requires resolving the parent organization; that enhancement can be
- * added later if needed.
+ * Fetch all members of a team handling GitHub API pagination.
+ * Supports both organization teams (via /members) and enterprise teams
+ * (via /memberships with X-GitHub-Api-Version: 2026-03-10).
  *
  * @param options Options containing scope/org/team information
  * @param headers Headers (with Authorization) forwarded from the incoming request
  * @returns Array of team member objects returned by the GitHub API
  */
 export async function fetchAllTeamMembers(options: Options, headers: HeadersInit): Promise<TeamMember[]> {
-  // Only proceed when an organization + team slug are both present
   if (!options.githubTeam) {
     return [];
   }
@@ -49,27 +47,58 @@ export async function fetchAllTeamMembers(options: Options, headers: HeadersInit
   let page = 1;
   const members: TeamMember[] = [];
 
-  /*
-   * Loop until an empty page (or a short page) is returned. We purposely do
-   * not rely on the Link header to keep the implementation simple & robust
-   * under mocking. If rate limiting becomes a concern this can be replaced
-   * with Link header parsing.
-   */
+  // Build headers: add API version for enterprise team memberships
+  const fetchHeaders: Record<string, string> = {};
+  if (headers instanceof Headers) {
+    for (const [key, value] of headers.entries()) {
+      fetchHeaders[key] = value;
+    }
+  } else if (typeof headers === 'object') {
+    Object.assign(fetchHeaders, headers);
+  }
+  if (options.scope === 'enterprise') {
+    delete fetchHeaders['x-github-api-version'];
+    fetchHeaders['X-GitHub-Api-Version'] = '2026-03-10';
+  }
+
   while (true) {
     const pageData = await $fetch<TeamMember[]>(membersUrl, {
-      headers,
+      headers: fetchHeaders,
       params: { per_page: perPage, page }
     });
 
     if (!Array.isArray(pageData) || pageData.length === 0) break;
-    members.push(...pageData);
+    // Normalize: enterprise /memberships may nest user data under a `user` property
+    for (const item of pageData) {
+      const member = normalizeTeamMember(item);
+      if (member) members.push(member);
+    }
     if (pageData.length < perPage) break; // last page
     page += 1;
   }
 
   return members;
 }
 
+/**
+ * Normalize a team member response item into {login, id}.
+ * Handles both flat user objects and potentially nested membership objects.
+ */
+function normalizeTeamMember(item: Record<string, unknown>): TeamMember | null {
+  // Flat user object (standard shape from both /members and /memberships)
+  if (typeof item.login === 'string' && typeof item.id === 'number') {
+    return item as TeamMember;
+  }
+  // Nested membership object (defensive: { user: { login, id } })
+  if (item.user && typeof item.user === 'object') {
+    const user = item.user as Record<string, unknown>;
+    if (typeof user.login === 'string' && typeof user.id === 'number') {
+      return user as TeamMember;
+    }
+  }
+  return null;
+}
+
 /**
  * Deduplicates seats by user ID, keeping the seat with the most recent activity.
  * This handles enterprise scenarios where users are assigned to multiple organizations.

server/api/teams.ts

@@ -74,14 +74,26 @@ export async function getTeams(event: H3Event<EventHandlerRequest>): Promise<Tea
     // Build base URL based on scope
     const baseUrl = options.getTeamsApiUrl()
 
+    // Build headers: start from auth middleware headers, add API version for enterprise teams
+    const fetchHeaders: Record<string, string> = {}
+    if (event.context.headers instanceof Headers) {
+        for (const [key, value] of event.context.headers.entries()) {
+            fetchHeaders[key] = value
+        }
+    }
+    if (options.scope === 'enterprise') {
+        delete fetchHeaders['x-github-api-version']
+        fetchHeaders['X-GitHub-Api-Version'] = '2026-03-10'
+    }
+
     const allTeams: Team[] = []
     let nextUrl: string | null = `${baseUrl}?per_page=100`
     let page = 1
 
     while (nextUrl) {
         logger.info(`Fetching teams page ${page} from ${nextUrl}`)
         const res = await $fetch.raw(nextUrl, {
-            headers: event.context.headers
+            headers: fetchHeaders
         })
 
         const data = res._data as GitHubTeam[]

server/services/user-metrics-aggregator.ts

@@ -37,8 +37,13 @@ export function aggregateTeamMetrics(
   userRecords: UserDayRecord[],
   teamLogins: Set<string>
 ): OrgReport {
-  // Filter to only records for team members
-  const teamRecords = userRecords.filter(r => teamLogins.has(r.user_login));
+  // Build case-insensitive login set for robust matching
+  const normalizedLogins = new Set(Array.from(teamLogins).map(l => l.toLowerCase()));
+
+  // Filter to only records for team members (case-insensitive login match)
+  const teamRecords = userRecords.filter(r =>
+    r.user_login && normalizedLogins.has(r.user_login.toLowerCase())
+  );
 
   // Group by day
   const byDay = new Map<string, UserDayRecord[]>();

shared/utils/metrics-util-v2.ts

@@ -235,6 +235,23 @@ export async function getMetricsDataV2(event: H3Event<EventHandlerRequest>): Pro
     });
   }
 
+  // Team-scoped direct API path: fetch user-level records, filter by team, aggregate
+  if (options.githubTeam) {
+    logger.info(`Direct API team path: resolving members for team "${options.githubTeam}" in ${identifier}`);
+    const teamMembers = await fetchAllTeamMembers(options, event.context.headers);
+    if (teamMembers.length === 0) {
+      logger.info('No team members found — returning empty metrics');
+      return { metrics: [], reportData: [] };
+    }
+    const teamLogins = new Set(teamMembers.map(m => m.login));
+
+    const request: MetricsReportRequest = { scope: options.scope!, identifier };
+    const userDayRecords = await fetchRawUserDayRecords(request, event.context.headers);
+    logger.info(`Aggregating team metrics from ${userDayRecords.length} user-day records (${teamMembers.length} team members)`);
+    const report = aggregateTeamMetrics(userDayRecords, teamLogins);
+    return buildFilteredResult(report, options);
+  }
+
   logger.info('Using new Copilot Metrics API (direct, no DB)');
   const result = await fetchFromNewApi(options, event.context.headers);
   return sortMetricsDataResult({

tests/MainComponent.hiddenTabs.spec.ts

@@ -72,18 +72,18 @@ describe('MainComponent hidden tabs filtering', () => {
 
   // Historical mode tests
   describe('auto-hide teams tab based on historical mode', () => {
-    test('should hide teams tab when historical mode is false', () => {
+    test('should always keep teams tab regardless of historical mode (teams now work in direct API mode)', () => {
       const tabs = ['organization', 'teams', ...ALL_BASE_TABS]
       const result = applyHistoricalModeFilter(tabs, false)
-      expect(result).not.toContain('teams')
+      expect(result).toContain('teams')
       expect(result).toContain('organization')
       expect(result).toContain('languages')
     })
 
-    test('should hide teams tab when historical mode is string "false"', () => {
+    test('should keep teams tab when historical mode is string "false"', () => {
       const tabs = ['organization', 'teams', ...ALL_BASE_TABS]
       const result = applyHistoricalModeFilter(tabs, 'false')
-      expect(result).not.toContain('teams')
+      expect(result).toContain('teams')
     })
 
     test('should keep teams tab when historical mode is true', () => {
@@ -98,10 +98,10 @@ describe('MainComponent hidden tabs filtering', () => {
       expect(result).toContain('teams')
     })
 
-    test('should not affect other tabs when hiding teams', () => {
+    test('should not affect other tabs', () => {
       const tabs = ['organization', 'teams', ...ALL_BASE_TABS]
       const result = applyHistoricalModeFilter(tabs, false)
-      expect(result).toHaveLength(tabs.length - 1)
+      expect(result).toHaveLength(tabs.length)
       ALL_BASE_TABS.forEach(tab => expect(result).toContain(tab))
     })
 

tests/Options.spec.ts

@@ -602,6 +602,55 @@ describe('Options', () => {
     })
   })
 
+  describe('getTeamMembersApiUrl', () => {
+    test('generates correct URL for organization scope', () => {
+      const options = new Options({
+        scope: 'organization',
+        githubOrg: 'test-org',
+        githubTeam: 'test-team'
+      })
+      
+      expect(options.getTeamMembersApiUrl()).toBe('https://api.github.com/orgs/test-org/teams/test-team/members')
+    })
+
+    test('generates correct URL for enterprise scope (uses /memberships)', () => {
+      const options = new Options({
+        scope: 'enterprise',
+        githubEnt: 'test-ent',
+        githubTeam: 'test-team'
+      })
+      
+      expect(options.getTeamMembersApiUrl()).toBe('https://api.github.com/enterprises/test-ent/teams/test-team/memberships')
+    })
+
+    test('throws error for organization scope without org or team', () => {
+      const options = new Options({
+        scope: 'organization',
+        githubOrg: 'test-org'
+      })
+      
+      expect(() => options.getTeamMembersApiUrl()).toThrow('GitHub organization and team must be set for organization scope')
+    })
+
+    test('throws error for enterprise scope without ent or team', () => {
+      const options = new Options({
+        scope: 'enterprise',
+        githubEnt: 'test-ent'
+      })
+      
+      expect(() => options.getTeamMembersApiUrl()).toThrow('GitHub enterprise and team must be set for enterprise scope')
+    })
+
+    test('throws error for invalid scope', () => {
+      const options = new Options({
+        scope: 'invalid-scope' as Scope,
+        githubTeam: 'test-team'
+      })
+      
+      expect(() => options.getTeamMembersApiUrl()).toThrow('Invalid scope: invalid-scope')
+    })
+  })
+
   describe('getMockDataPath', () => {
     test('returns correct path for organization scope', () => {
       const options1 = new Options({ scope: 'organization' })

tests/user-metrics-aggregator.spec.ts

@@ -318,4 +318,17 @@ describe('aggregateTeamMetrics', () => {
     expect(result.day_totals[0].daily_active_users).toBe(1);
     expect(result.day_totals[1].daily_active_users).toBe(1);
   });
+
+  it('matches team members case-insensitively', () => {
+    const records = [
+      makeUser('Alice', 1, '2026-02-10'),
+      makeUser('BOB', 2, '2026-02-10'),
+      makeUser('charlie', 3, '2026-02-10'),
+    ];
+    // Team logins in different casing than user records
+    const result = aggregateTeamMetrics(records, new Set(['alice', 'bob']));
+
+    expect(result.day_totals).toHaveLength(1);
+    expect(result.day_totals[0].daily_active_users).toBe(2);
+  });
 });