@thinkai/tai-api-contract 2.63.0 → 2.65.0

package/src/index.ts

@@ -1537,6 +1537,169 @@ export interface SdlcDrilldownDto {
   nextCursor?: string;
 }
 
+/** Shared Insights & Recommendations response meta (`_meta.isMock` is always false in production). */
+export interface InsightsResponseMeta {
+  syncedAt: string;
+  isMock: false;
+}
+
+export type InsightsVerdictStatus = "healthy" | "watch" | "at-risk";
+
+export interface InsightsRecommendationsVerdictSummary {
+  /** Merged-PR volume ratio vs prior equal-length window. */
+  productivityMultiplier: number;
+  productivityStatus: InsightsVerdictStatus;
+  ciFailRatePct: number;
+  qualityStatus: InsightsVerdictStatus;
+  spendPerMergedPrUsd: number;
+  spendPerMergedPrPrevUsd: number;
+  costStatus: InsightsVerdictStatus;
+}
+
+export interface InsightsRoiEngineerPoint {
+  id: string;
+  name: string;
+  team: string;
+  spendUsd: number;
+  mergedPrs: number;
+}
+
+export interface InsightsRecommendationsRoiQuadrant {
+  medianSpendUsd: number;
+  medianMergedPrs: number;
+  engineers: InsightsRoiEngineerPoint[];
+  correlationHint: string;
+}
+
+export interface InsightsVelocityQualityWeek {
+  weekStartIso: string;
+  mergedPrs: number;
+  ciFailRatePct: number;
+}
+
+export interface InsightsRecommendationsVelocityQuality {
+  weeks: InsightsVelocityQualityWeek[];
+  targetFailRatePct: number;
+  volumeGrowthPct: number;
+}
+
+export const INSIGHTS_REVIEW_STAGE_IDS = [
+  "open-review",
+  "review-approval",
+  "approval-merge",
+  "merged",
+] as const;
+export type InsightsReviewStageId = (typeof INSIGHTS_REVIEW_STAGE_IDS)[number];
+
+export interface InsightsReviewStage {
+  id: InsightsReviewStageId;
+  name: string;
+  medianHours: number;
+  trendPct: number;
+}
+
+export interface InsightsReviewerLoadItem {
+  id: string;
+  name: string;
+  reviewsCount: number;
+  sharePct: number;
+}
+
+export interface InsightsRecommendationsReviewPipeline {
+  stages: InsightsReviewStage[];
+  bottleneckStageId: InsightsReviewStageId;
+  reviewerLoad: InsightsReviewerLoadItem[];
+}
+
+export interface InsightsCostPerPrTeam {
+  id: string;
+  name: string;
+  activeAi: number;
+  spendUsd: number;
+  mergedPrs: number;
+  costPerPrUsd: number;
+  changePct: number;
+}
+
+export interface InsightsRecommendationsCostPerPr {
+  orgAvgCostUsd: number;
+  orgAvgPrevUsd: number;
+  teams: InsightsCostPerPrTeam[];
+}
+
+export interface InsightsAdoptionTeam {
+  id: string;
+  name: string;
+  activeAi: number;
+  totalMembers: number;
+  readinessPct: number;
+  outputPerEngPerWeek: number;
+}
+
+export interface InsightsRecommendationsAdoptionGap {
+  totalContributors: number;
+  activeContributors: number;
+  upliftPct: number;
+  teams: InsightsAdoptionTeam[];
+}
+
+export const INSIGHTS_RECOMMENDATION_MODULE_IDS = [
+  "mod-spend-vs-output",
+  "mod-velocity-vs-quality",
+  "mod-review-bottleneck",
+  "mod-cost-per-pr",
+  "mod-adoption-gap",
+] as const;
+export type InsightsRecommendationModuleId = (typeof INSIGHTS_RECOMMENDATION_MODULE_IDS)[number];
+
+export type InsightsRecommendationImpact = "high" | "medium";
+export type InsightsRecommendationTone = "action" | "no-action";
+export type InsightsEvidenceLinkKind = "user-spend" | "team" | "contributor" | "repo" | "module";
+
+export interface InsightsEvidenceChip {
+  label: string;
+  kind: InsightsEvidenceLinkKind;
+  targetId: string;
+}
+
+export interface InsightsRecommendationEvidenceGroup {
+  title: string;
+  chips: InsightsEvidenceChip[];
+}
+
+export interface InsightsRecommendationDto {
+  moduleId: InsightsRecommendationModuleId;
+  moduleName: string;
+  tone: InsightsRecommendationTone;
+  impact: InsightsRecommendationImpact;
+  headline: string;
+  observed: string;
+  action: string;
+  benefit: string;
+  confidencePct: number;
+  evidence: InsightsRecommendationEvidenceGroup[];
+}
+
+export type WithInsightsMeta<T> = T & { _meta: InsightsResponseMeta };
+
+export type InsightsRecommendationsVerdictSummaryResponse =
+  WithInsightsMeta<InsightsRecommendationsVerdictSummary>;
+export type InsightsRecommendationsRoiQuadrantResponse =
+  WithInsightsMeta<InsightsRecommendationsRoiQuadrant>;
+export type InsightsRecommendationsVelocityQualityResponse =
+  WithInsightsMeta<InsightsRecommendationsVelocityQuality>;
+export type InsightsRecommendationsReviewPipelineResponse =
+  WithInsightsMeta<InsightsRecommendationsReviewPipeline>;
+export type InsightsRecommendationsCostPerPrResponse =
+  WithInsightsMeta<InsightsRecommendationsCostPerPr>;
+export type InsightsRecommendationsAdoptionGapResponse =
+  WithInsightsMeta<InsightsRecommendationsAdoptionGap>;
+
+export interface InsightsRecommendationsListResponse {
+  items: InsightsRecommendationDto[];
+  _meta: InsightsResponseMeta;
+}
+
 export {
   JOURNEY_STEP_IDS,
   JOURNEY_STEP_REGISTRY,