feat: Per-user Copilot usage & premium request analytics (#316)

Author: Copilot

.env.example

@@ -28,7 +28,7 @@ NUXT_PUBLIC_USING_GITHUB_AUTH=false
 # ------------------------------------------------------------------------------
 
 # GitHub Personal Access Token for API calls
-# Required scopes: copilot, manage_billing:copilot, manage_billing:enterprise, read:enterprise, read:org
+# Required permissions: Read access to members, organization copilot metrics, and organization copilot seat management
 # NUXT_GITHUB_TOKEN=ghp_your_token_here
 
 # Session password for encrypting user sessions (REQUIRED!)

.github/copilot-instructions.md

@@ -87,7 +87,7 @@ Always reference these instructions first and fallback to search or bash command
   - Uses sample data for development and testing
 - **Real GitHub data**: Requires GitHub Personal Access Token
   - `NUXT_GITHUB_TOKEN=<your_token>`
-  - Token needs scopes: copilot, manage_billing:copilot, manage_billing:enterprise, read:enterprise, read:org
+  - Token needs permissions: Read access to members, organization copilot metrics, and organization copilot seat management
 
 ### Scope Configuration
 - **NUXT_PUBLIC_SCOPE**: Sets default scope ('organization', 'enterprise', 'team-organization', 'team-enterprise')

API_MIGRATION_DESIGN.md

@@ -33,7 +33,7 @@ The application currently operates as a **stateless web application** with the f
 
 4. **Authentication**
    - Personal Access Tokens (PAT) or GitHub OAuth
-   - Token scopes: `copilot`, `manage_billing:copilot`, `read:enterprise`, `read:org`
+   - Token permissions: Read access to members, organization copilot metrics, and organization copilot seat management
 
 ## New API Requirements
 
@@ -56,7 +56,7 @@ The application currently operates as a **stateless web application** with the f
    - Must enable "Copilot usage metrics" policy
 
 4. **Authentication**
-   - Same token scopes: `manage_billing:copilot` or `read:enterprise`
+   - Required permissions: Read access to members, organization copilot metrics, and organization copilot seat management
    - OAuth apps or fine-grained access tokens supported
 
 ## Proposed Architecture

API_QUICK_REFERENCE.md

@@ -53,19 +53,13 @@ GET https://api.github.com/enterprises/{enterprise}/copilot/metrics/reports/ente
 
 ## Authentication
 
-### Required Token Scopes (Same for Both APIs)
-
-**Classic PAT**:
-- `copilot` (for basic metrics)
-- `manage_billing:copilot` (for billing-related metrics)
-- `manage_billing:enterprise` (for enterprise billing)
-- `read:enterprise` (for enterprise metrics)
-- `read:org` (for organization metrics)
+### Required Token Permissions (Same for Both APIs)
 
 **Fine-grained Token**:
 - Repository access: Not required
-- Organization permissions: "View Copilot usage"
-- Enterprise permissions: "View Enterprise Copilot Metrics"
+- Read access to members
+- Organization copilot metrics
+- Organization copilot seat management
 
 ## Request/Response Examples
 
@@ -409,7 +403,7 @@ async function getMetrics(org: string, since: string, until: string) {
 **A**: Team metrics are included in organization/enterprise reports, but may require filtering
 
 ### Q: Can I still use the same authentication?
-**A**: Yes, token scopes are the same
+**A**: Yes, the required permissions are the same: Read access to members, organization copilot metrics, and organization copilot seat management
 
 ### Q: What about seats data?
 **A**: Seats API remains similar (separate endpoint, not affected by metrics API change)

DEPLOYMENT.md

@@ -284,11 +284,11 @@ or navigate using UI:
 2. Provide a home page URL: your company URL or just `http://localhost`.
 3. Add a callback URL for `http://localhost:3000/auth/github`. (We'll add the real redirect URL after the application is deployed.)
 4. Uncheck the "Webhook -> Active" checkbox.
-5. Set the scopes:
+5. Set the permissions:
    - Select **Organization permissions**.
-   - Under **GitHub Copilot Business**, select **Access: Read-only**.
-   - Under **Copilot Metrics**, select **Access: Read-only**. _(Required for v3.0+ — the new Copilot Usage Metrics API)_
    - Under **Members**, select **Access: Read-only**.
+   - Under **Copilot Metrics**, select **Access: Read-only**.
+   - Under **Copilot Seat Management**, select **Access: Read-only**.
 6. Click on 'Create GitHub App' and, in the following page, click on 'Generate a new client secret'.
 7. Note the `Client ID` and `Client Secret` (copy it to a secure location). This is required for the application to authenticate with GitHub.
 8. Install the app in the organization:

README.md

@@ -236,10 +236,10 @@ NUXT_PUBLIC_IS_DATA_MOCKED=false
 
 #### NUXT_GITHUB_TOKEN
 
-Specifies the GitHub Personal Access Token utilized for API requests. Generate this token with the following scopes: _copilot_, _manage_billing:copilot_, _manage_billing:enterprise_, _read:enterprise_, _read:org_.
+Specifies the GitHub Personal Access Token utilized for API requests. Generate this token with the following permissions: _Read access to members_, _organization copilot metrics_, and _organization copilot seat management_.
 
 > [!IMPORTANT]
-> **v3.0 Migration:** The new Copilot Usage Metrics API requires the **"Organization Copilot metrics: Read"** permission on your GitHub App (or the `read:org` scope for classic PATs). Without this, the new API endpoints will return 400/403 errors. See [GitHub App Registration](DEPLOYMENT.md#github-app-registration) for setup details.
+> **v3.0 Migration:** The new Copilot Usage Metrics API requires **Read access to members, organization copilot metrics, and organization copilot seat management** permissions. Without this, the new API endpoints will return 400/403 errors. See [GitHub App Registration](DEPLOYMENT.md#github-app-registration) for setup details.
 
 Token is not used in the frontend.
 

app/components/MainComponent.vue

@@ -86,7 +86,7 @@
 
     <div v-show="!apiError">
       <v-progress-linear v-show="!metricsReady" indeterminate color="indigo" />
-      <v-window v-show="(metricsReady && metrics.length) || (seatsReady && tab === 'seat analysis')" v-model="tab">
+      <v-window v-show="(metricsReady && metrics.length) || (seatsReady && tab === 'seat analysis') || (userMetricsReady && tab === 'user metrics')" v-model="tab">
         <v-window-item v-for="item in tabItems" :key="item" :value="item">
           <v-card flat>
             <MetricsViewer v-if="item === getDisplayTabName(itemName)" :metrics="metrics" :date-range-description="dateRangeDescription" />
@@ -103,14 +103,30 @@ v-if="item === 'copilot chat'" :metrics="metrics"
             <AgentActivityViewer v-if="item === 'agent activity'" :report-data="reportData" :date-range-description="dateRangeDescription" />
             <PullRequestViewer v-if="item === 'pull requests'" :report-data="reportData" :date-range-description="dateRangeDescription" />
             <AgentModeViewer v-if="item === 'github.com'" :original-metrics="originalMetrics" :date-range="dateRange" :date-range-description="dateRangeDescription" />
-            <SeatsAnalysisViewer v-if="item === 'seat analysis'" :seats="seats" />
+            <SeatsAnalysisViewer
+              v-if="item === 'seat analysis'"
+              :seats="seats"
+              :total-seats-count="seatsTotalCount"
+              :current-page="seatsCurrentPage"
+              :total-pages="seatsTotalPages"
+              :per-page="seatsPerPage"
+              :seats-history="seatsHistory"
+              @page-change="handleSeatsPageChange"
+            />
+            <UserMetricsViewer
+              v-if="item === 'user metrics'"
+              :user-metrics="userMetrics"
+              :date-range-description="dateRangeDescription"
+              :user-metrics-history="userMetricsHistory"
+              :query-params="seatsQueryParams"
+            />
             <ApiResponse
 v-if="item === 'api response'" :metrics="metrics" :original-metrics="originalMetrics"
               :seats="seats" />
           </v-card>
         </v-window-item>
         <v-alert
-          v-show="(metricsReady && metrics.length == 0 && tab !== 'seat analysis') || (seatsReady && seats.length == 0 && tab === 'seat analysis')"
+          v-show="(metricsReady && metrics.length == 0 && tab !== 'seat analysis' && tab !== 'user metrics') || (seatsReady && seats.length == 0 && tab === 'seat analysis') || (userMetricsReady && userMetrics.length == 0 && tab === 'user metrics')"
           density="compact" text="No data available to display" title="No data" type="warning" />
       </v-window>
 
@@ -123,7 +139,10 @@ import type { Metrics } from '@/model/Metrics';
 import type { CopilotMetrics } from '@/model/Copilot_Metrics';
 import type { MetricsApiResponse } from '@/types/metricsApiResponse';
 import type { Seat } from "@/model/Seat";
-import type { ReportDayTotals } from "../../server/services/github-copilot-usage-api";
+import type { SeatsApiResponse } from '../server/api/seats';
+import type { ReportDayTotals, UserTotals } from "../../server/services/github-copilot-usage-api";
+import type { SeatHistoryEntry } from "../../server/storage/seats-storage";
+import type { UserMetricsHistoryEntry } from "../../server/storage/user-metrics-storage";
 import type { H3Error } from 'h3'
 
 //Components
@@ -137,6 +156,7 @@ import AgentModeViewer from './AgentModeViewer.vue'
 import AgentActivityViewer from './AgentActivityViewer.vue'
 import PullRequestViewer from './PullRequestViewer.vue'
 import DateRangeSelector from './DateRangeSelector.vue'
+import UserMetricsViewer from './UserMetricsViewer.vue'
 import { Options } from '@/model/Options';
 import { useRoute } from 'vue-router';
 
@@ -152,7 +172,8 @@ export default defineNuxtComponent({
     AgentModeViewer,
     AgentActivityViewer,
     PullRequestViewer,
-    DateRangeSelector
+    DateRangeSelector,
+    UserMetricsViewer
   },
   methods: {
     logout() {
@@ -255,12 +276,45 @@ export default defineNuxtComponent({
             break;
         }
       }
+    },
+    /** Handle page navigation from SeatsAnalysisViewer paginator */
+    async handleSeatsPageChange(page: number) {
+      const { data: seatsData, error: seatsError, execute } = this.seatsFetch;
+      // Update setup ref so the reactive query re-evaluates with the new page
+      (this as any).seatsCurrentPage = page;
+      await execute();
+      if (!seatsError.value) {
+        const resp = seatsData.value as SeatsApiResponse | null;
+        if (resp) {
+          this.seats            = resp.seats        || [];
+          this.seatsTotalCount  = resp.total_seats  || 0;
+          this.seatsCurrentPage = resp.page         || page;
+          this.seatsTotalPages  = resp.total_pages  || 1;
+        }
+      }
+    },
+    /** Fetch seats and user-metrics history (DB / historical mode) */
+    async fetchHistory() {
+      const options = Options.fromRoute(this.route);
+      const params  = options.toParams();
+      const qs      = new URLSearchParams(params).toString();
+
+      try {
+        const [seatsH, userH] = await Promise.all([
+          $fetch<SeatHistoryEntry[]>(`/api/seats-history${qs ? '?' + qs : ''}`).catch(() => []),
+          $fetch<UserMetricsHistoryEntry[]>(`/api/user-metrics-history${qs ? '?' + qs : ''}`).catch(() => []),
+        ]);
+        this.seatsHistory        = seatsH;
+        this.userMetricsHistory  = userH;
+      } catch {
+        // history is non-critical — swallow errors
+      }
     }
   },
 
   data() {
     return {
-      tabItems: ['languages', 'editors', 'copilot chat', 'agent activity', 'pull requests', 'github.com', 'seat analysis', 'api response'],
+      tabItems: ['languages', 'editors', 'copilot chat', 'agent activity', 'pull requests', 'github.com', 'seat analysis', 'user metrics', 'api response'],
       tab: null,
       dateRangeDescription: 'Over the last 28 days',
       isLoading: false,
@@ -270,6 +324,14 @@ export default defineNuxtComponent({
       reportData: [] as ReportDayTotals[],
       seatsReady: false,
       seats: [] as Seat[],
+      seatsTotalCount:  0,
+      seatsCurrentPage: 1,
+      seatsTotalPages:  1,
+      seatsPerPage:     300,
+      seatsHistory:     [] as SeatHistoryEntry[],
+      userMetricsReady: false,
+      userMetrics: [] as UserTotals[],
+      userMetricsHistory: [] as UserMetricsHistoryEntry[],
       apiError: undefined as string | undefined,
       showMigrationBanner: true,
       config: null as ReturnType<typeof useRuntimeConfig> | null,
@@ -295,16 +357,39 @@ export default defineNuxtComponent({
       await this.fetchMetrics();
 
       const { data: seatsData, error: seatsError, execute: executeSeats } = this.seatsFetch;
+      const { data: userMetricsData, error: userMetricsError, execute: executeUserMetrics } = this.userMetricsFetch;
 
       if (!this.signInRequired) {
         await executeSeats();
 
         if (seatsError.value) {
           this.processError(seatsError.value as H3Error);
         } else {
-          this.seats = (seatsData.value as Seat[]) || [];
+          const resp = seatsData.value as SeatsApiResponse | null;
+          if (resp) {
+            this.seats          = resp.seats          || [];
+            this.seatsTotalCount = resp.total_seats   || 0;
+            this.seatsCurrentPage = resp.page         || 1;
+            this.seatsTotalPages  = resp.total_pages  || 1;
+          }
           this.seatsReady = true;
         }
+
+        await executeUserMetrics();
+
+        if (userMetricsError.value) {
+          // User metrics errors are non-fatal — log but don't block the UI
+          console.warn('User metrics fetch failed:', userMetricsError.value);
+        } else {
+          this.userMetrics = (userMetricsData.value as UserTotals[]) || [];
+          this.userMetricsReady = true;
+        }
+
+        // Fetch history data if historical mode is enabled
+        const config = useRuntimeConfig();
+        if (config.public.enableHistoricalMode) {
+          await this.fetchHistory();
+        }
       }
 
     } catch (error) {
@@ -322,6 +407,7 @@ export default defineNuxtComponent({
     const dateRange = ref({ since: undefined as string | undefined, until: undefined as string | undefined });
     const isLoading = ref(false);
     const route = ref(useRoute());
+    const seatsCurrentPage = ref(1);
 
     const signInRequired = computed(() => {
       return config.public.usingGithubAuth && !loggedIn.value;
@@ -330,6 +416,24 @@ export default defineNuxtComponent({
     const seatsFetch = useFetch('/api/seats', {
       server: true,
       immediate: !signInRequired.value,
+      query: computed(() => {
+        const options = Options.fromRoute(route.value);
+        return { ...options.toParams(), page: String(seatsCurrentPage.value), per_page: '300' };
+      })
+    });
+
+    /** Scope + org/ent params forwarded to history endpoints and user-trend API */
+    const seatsQueryParams = computed(() => {
+      const options = Options.fromRoute(route.value);
+      const p = options.toParams();
+      // Only forward identity params, not pagination
+      const { since: _s, until: _u, ...rest } = p;
+      return rest;
+    });
+
+    const userMetricsFetch = useFetch('/api/user-metrics', {
+      server: true,
+      immediate: false,
       query: computed(() => {
         const options = Options.fromRoute(route.value);
         return options.toParams();
@@ -344,9 +448,12 @@ export default defineNuxtComponent({
       signInRequired,
       user,
       seatsFetch,
+      userMetricsFetch,
       dateRange,
       isLoading,
       route,
+      seatsCurrentPage,
+      seatsQueryParams,
     };
   },
 })