@thinkai/tai-api-contract 2.5.2 → 2.5.17

package/src/index.ts

@@ -424,6 +424,359 @@ export interface DashboardProductivityHistoryDto {
   }[];
 }
 
+/** Applied Measure filters echoed in aggregated-teams responses. */
+export interface ProductivityInsightsAggregatedTeamsScopeDto {
+  department: string;
+  team: string;
+}
+
+/** One weekly bucket in an aggregated team row. */
+export interface ProductivityInsightsAggregatedTeamWeekDto {
+  bucketStart: string;
+  bucketEnd: string;
+  weekLabel?: string;
+  mergedPrCount: number;
+  failRatePercent: number;
+}
+
+/** Per-team rollup for Productivity insights (Aggregated Teams). */
+export interface ProductivityInsightsAggregatedTeamRowDto {
+  teamId: string;
+  teamName: string;
+  headcount: number;
+  managerLabel?: string;
+  weeks: ProductivityInsightsAggregatedTeamWeekDto[];
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/productivity-insights/aggregated-teams */
+export interface ProductivityInsightsAggregatedTeamsDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  teams: ProductivityInsightsAggregatedTeamRowDto[];
+}
+
+/** One weekly bucket in a merged PR trends series. */
+export interface ProductivityInsightsMergedPrTrendWeekDto {
+  bucketStart: string;
+  bucketEnd: string;
+  weekLabel?: string;
+  mergedPrCount: number;
+}
+
+/** Per-contributor merged PR weekly series. */
+export interface ProductivityInsightsMergedPrContributorRowDto {
+  personId: string;
+  personName: string;
+  teamName?: string;
+  weeks: ProductivityInsightsMergedPrTrendWeekDto[];
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/productivity-insights/merged-pr-trends */
+export interface ProductivityInsightsMergedPrTrendsDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  weeks: ProductivityInsightsMergedPrTrendWeekDto[];
+  contributors: ProductivityInsightsMergedPrContributorRowDto[];
+}
+
+/** One row in the top-teams (leaders) widget. */
+export interface ProductivityInsightsTeamLeaderItemDto {
+  rank: number;
+  teamId: string;
+  teamName: string;
+  subtitle?: string;
+  periodAvgMergedPrs: number;
+  deltaVsPeriodAvgPercent: number;
+  avgFailRatePercent?: number;
+}
+
+/** Period summary for a single-team drilldown. */
+export interface ProductivityInsightsTeamSummaryDto {
+  totalMergedPrs: number;
+  avgMergedPrsPerWeek: number;
+  avgFailRatePercent: number;
+  headcount: number;
+}
+
+/** Single-team drilldown payload. */
+export interface ProductivityInsightsTeamDetailDto {
+  teamId: string;
+  teamName: string;
+  headcount: number;
+  managerLabel?: string;
+  weeks: ProductivityInsightsAggregatedTeamWeekDto[];
+  summary: ProductivityInsightsTeamSummaryDto;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/productivity-insights/teams */
+export interface ProductivityInsightsTeamsResponseDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  /** Top-ranked teams when `teamId` query is omitted. */
+  items?: ProductivityInsightsTeamLeaderItemDto[];
+  /** Single-team drilldown when `teamId` query is set. */
+  team?: ProductivityInsightsTeamDetailDto;
+}
+
+/** Org-chart person profile for contributor drilldown. */
+export interface ProductivityInsightsContributorProfileDto {
+  id: string;
+  name: string;
+  title?: string;
+  team?: string;
+  department?: string;
+}
+
+/** One calendar day in contributor activity heatmap. */
+export interface ProductivityInsightsContributorActivityDayDto {
+  date: string;
+  dayIndex: number;
+  mergedPrCount: number;
+  mergedPrs: string[];
+  absent: boolean;
+  absenceType?: string;
+  failureSignal: boolean;
+  failures: string[];
+}
+
+/** One weekly row in contributor activity heatmap. */
+export interface ProductivityInsightsContributorActivityWeekDto {
+  label: string;
+  bucketStart: string;
+  bucketEnd: string;
+  days: ProductivityInsightsContributorActivityDayDto[];
+}
+
+/** Summary stats for contributor activity drilldown. */
+export interface ProductivityInsightsContributorActivitySummaryDto {
+  totalMergedPrs: number;
+  avgMergedPrsPerWeek: number;
+  totalAbsenceDays: number;
+  avgFailRate: number;
+  mergedPrDelta: number;
+  avgMergedPrsPerWeekDelta: number;
+  totalAbsenceDaysDelta: number;
+  avgFailRateDelta: number;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/productivity-insights/contributors/:contributorId */
+export interface ProductivityInsightsContributorDetailDto {
+  workspaceId: string;
+  contributorId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  contributor: ProductivityInsightsContributorProfileDto;
+  weeks: ProductivityInsightsContributorActivityWeekDto[];
+  summary: ProductivityInsightsContributorActivitySummaryDto;
+}
+
+/** One row in the needs-attention (laggards) widget. */
+export interface ProductivityInsightsNeedsAttentionItemDto {
+  rank: number;
+  entityId: string;
+  entityType: "team" | "contributor";
+  name: string;
+  subtitle?: string;
+  periodAvgMergedPrs: number;
+  deltaVsPeriodAvgPercent: number;
+  avgFailRatePercent?: number;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/productivity-insights/needs-attention */
+export interface ProductivityInsightsNeedsAttentionDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  entityType: "teams" | "contributors";
+  generatedAt: string;
+  items: ProductivityInsightsNeedsAttentionItemDto[];
+}
+
+/** One weekly bucket in an AI usage & spend aggregated team row. */
+export interface AiUsageSpendAggregatedTeamWeekDto {
+  bucketStart: string;
+  bucketEnd: string;
+  weekLabel?: string;
+  tokenCount: number;
+  spendCents: number;
+  activeUsers: number;
+}
+
+/** Per-team AI usage & spend rollup for Measure Aggregated Teams view. */
+export interface AiUsageSpendAggregatedTeamRowDto {
+  teamId: string;
+  teamName: string;
+  headcount: number;
+  managerLabel?: string;
+  weeks: AiUsageSpendAggregatedTeamWeekDto[];
+}
+
+/** Portfolio totals for AI usage & spend KPI strip. */
+export interface AiUsageSpendAggregatedTeamsSummaryDto {
+  totalTokenCount: number;
+  totalSpendCents: number;
+  activeUsers: number;
+  activeTools: number;
+  totalEngineers: number;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/aggregated-teams */
+export interface AiUsageSpendAggregatedTeamsDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  teams: AiUsageSpendAggregatedTeamRowDto[];
+  summary: AiUsageSpendAggregatedTeamsSummaryDto;
+}
+
+/** Per-contributor AI usage & spend rollup for Measure Individual Contributors view. */
+export interface AiUsageSpendAggregatedContributorRowDto {
+  contributorId: string;
+  contributorName: string;
+  title?: string;
+  team?: string;
+  department?: string;
+  weeks: AiUsageSpendAggregatedTeamWeekDto[];
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/aggregated-contributors */
+export interface AiUsageSpendAggregatedContributorsDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  contributors: AiUsageSpendAggregatedContributorRowDto[];
+  summary: AiUsageSpendAggregatedTeamsSummaryDto;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/contributor-tool-heatmap */
+export interface AiUsageSpendContributorToolHeatmapDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  contributors: AiUsageSpendAggregatedContributorRowDto[];
+}
+
+/** One card in the AI usage & spend key insights panel. */
+export interface AiUsageSpendKeyInsightItemDto {
+  id: string;
+  tone: "positive" | "warning" | "neutral";
+  text: string;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/key-insights */
+export interface AiUsageSpendKeyInsightsDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  items: AiUsageSpendKeyInsightItemDto[];
+}
+
+/** Whether AI-assisted code % is from ingest or token heuristics. */
+export type AiAssistedCodeDataQuality = "estimated" | "measured";
+
+/** One weekly bucket in the AI-assisted code percentage series. */
+export interface AiUsageSpendAiAssistedCodeWeekDto {
+  bucketStart: string;
+  bucketEnd: string;
+  weekLabel?: string;
+  aiAssistedCodePercent: number;
+  totalLoc: number;
+  aiLoc: number;
+  humanLoc: number;
+  dataQuality: AiAssistedCodeDataQuality;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/ai-assisted-code-percentage */
+export interface AiUsageSpendAiAssistedCodePercentageDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  aiAssistedCodePercent: number;
+  dataQuality: AiAssistedCodeDataQuality;
+  deltaVsPriorPeriodPercent: number;
+  totalLoc: number;
+  aiLoc: number;
+  humanLoc: number;
+  targetMinPercent?: number;
+  targetMaxPercent?: number;
+  weeks: AiUsageSpendAiAssistedCodeWeekDto[];
+}
+
+/** One provider row in AI tool usage/spend rollups. */
+export interface AiUsageSpendAiToolUsageSpendProviderItemDto {
+  providerId: string;
+  providerName: string;
+  tokenCount: number;
+  spendCents: number;
+  activeUsers: number;
+}
+
+/** One model row in AI tool usage/spend rollups. */
+export interface AiUsageSpendAiToolUsageSpendModelItemDto {
+  providerId: string;
+  providerName: string;
+  modelName: string;
+  tokenCount: number;
+  spendCents: number;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/ai-tool-usage-spend */
+export interface AiUsageSpendAiToolUsageSpendDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  totalEngineers: number;
+  providers: AiUsageSpendAiToolUsageSpendProviderItemDto[];
+  models: AiUsageSpendAiToolUsageSpendModelItemDto[];
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/team-tool-heatmap */
+export interface AiUsageSpendTeamToolHeatmapDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  teams: AiUsageSpendAggregatedTeamRowDto[];
+}
+
+/** One weekly bucket in the ROI / productivity signal panel. */
+export interface AiUsageSpendRoiProductivitySignalWeekDto {
+  bucketStart: string;
+  bucketEnd: string;
+  weekLabel?: string;
+  mergedPrCount: number;
+  tokenCount: number;
+}
+
+/** Response for GET /workspaces/:workspaceId/insights/ai-usage-spend/roi-productivity-signal */
+export interface AiUsageSpendRoiProductivitySignalDto {
+  workspaceId: string;
+  range: "4w" | "8w" | "q";
+  scope: ProductivityInsightsAggregatedTeamsScopeDto;
+  generatedAt: string;
+  totalMergedPrs: number;
+  totalSpendCents: number;
+  activeUsers: number;
+  totalEngineers: number;
+  aiAssistedPrRatio: number;
+  prThroughputDeltaPercent: number;
+  usageDeltaPercent: number;
+  weeks: AiUsageSpendRoiProductivitySignalWeekDto[];
+}
+
 /** Appeal: user contests a misattributed event. Lifecycle: pending → approved | rejected. */
 export interface AppealDto {
   id: string;