@thinkai/tai-api-contract 2.34.0-pr.810.e54f7dcd → 2.35.0-pr.811.d57af044

package/src/index.ts

@@ -302,10 +302,6 @@ export interface DashboardProductivityMetricsDto {
   quality?: {
     codeReviewHoursPerWeek?: number;
     buildFailuresPerWeek?: number;
-    /** Share of completed CI runs that failed (GitHub Actions / Checks). */
-    ciBuildFailRatePercent?: number;
-    /** Count of build.failed events in the bucket window. */
-    ciBuildFailuresCount?: number;
     avgTimeToFixBuildHours?: number;
     testCoveragePercent?: number;
     escapedBugsCount?: number;
@@ -464,10 +460,6 @@ export interface ProductivityInsightsAggregatedTeamWeekDto {
   weekLabel?: string;
   mergedPrCount: number;
   failRatePercent: number;
-  /** GitHub Actions CI build failure rate (failed / (failed + passed) * 100). */
-  ciFailRatePercent?: number;
-  /** Count of build.failed events in the bucket when CI ingest is enabled. */
-  ciBuildFailuresCount?: number;
   avgReviewWaitHours?: number;
   avgApprovalHours?: number;
   avgTimeToMergeHours?: number;
@@ -492,8 +484,6 @@ export interface ProductivityInsightsAggregatedTeamsDto {
   range: "4w" | "8w" | "q" | "12w" | "16w";
   scope: ProductivityInsightsAggregatedTeamsScopeDto;
   generatedAt: string;
-  /** True when the workspace has opted in to GitHub Actions CI ingest. */
-  githubActionsCiEnabled?: boolean;
   teams: ProductivityInsightsAggregatedTeamRowDto[];
 }
 
@@ -535,7 +525,6 @@ export interface ProductivityInsightsTeamLeaderItemDto {
   subtitle?: string;
   periodAvgMergedPrs: number;
   avgFailRatePercent?: number;
-  avgCiFailRatePercent?: number;
 }
 
 /** Period summary for a single-team drilldown. */
@@ -543,8 +532,6 @@ export interface ProductivityInsightsTeamSummaryDto {
   totalMergedPrs: number;
   avgMergedPrsPerWeek: number;
   avgFailRatePercent: number;
-  /** Average GitHub Actions CI build failure rate over the range when CI ingest is enabled. */
-  avgCiFailRatePercent?: number;
   headcount: number;
 }
 
@@ -573,8 +560,6 @@ export interface ProductivityInsightsTeamsResponseDto {
   year?: number;
   scope: ProductivityInsightsAggregatedTeamsScopeDto;
   generatedAt: string;
-  /** True when the workspace has opted in to GitHub Actions CI ingest. */
-  githubActionsCiEnabled?: boolean;
   /** Top-ranked teams when `teamId` query is omitted. */
   items?: ProductivityInsightsTeamLeaderItemDto[];
   /** Single-team drilldown when `teamId` query is set. */
@@ -628,14 +613,10 @@ export interface ProductivityInsightsContributorActivitySummaryDto {
   avgMergedPrsPerWeek: number;
   totalAbsenceDays: number;
   avgFailRate: number;
-  /** Average GitHub Actions CI build failure rate over the range when CI ingest is enabled. */
-  avgCiFailRate?: number;
   mergedPrDelta: number;
   avgMergedPrsPerWeekDelta: number;
   totalAbsenceDaysDelta: number;
   avgFailRateDelta: number;
-  /** Change in average CI build failure rate vs the prior comparison window. */
-  avgCiFailRateDelta?: number;
 }
 
 /** Response for GET /workspaces/:workspaceId/insights/productivity-insights/contributors/:contributorId */
@@ -647,8 +628,6 @@ export interface ProductivityInsightsContributorDetailDto {
   year?: number;
   scope: ProductivityInsightsAggregatedTeamsScopeDto;
   generatedAt: string;
-  /** True when the workspace has opted in to GitHub Actions CI ingest. */
-  githubActionsCiEnabled?: boolean;
   contributor: ProductivityInsightsContributorProfileDto;
   weeks: ProductivityInsightsContributorActivityWeekDto[];
   summary: ProductivityInsightsContributorActivitySummaryDto;
@@ -663,7 +642,6 @@ export interface ProductivityInsightsNeedsAttentionItemDto {
   subtitle?: string;
   periodAvgMergedPrs: number;
   avgFailRatePercent?: number;
-  avgCiFailRatePercent?: number;
 }
 
 /** Response for GET /workspaces/:workspaceId/insights/productivity-insights/needs-attention */
@@ -673,7 +651,6 @@ export interface ProductivityInsightsNeedsAttentionDto {
   scope: ProductivityInsightsAggregatedTeamsScopeDto;
   entityType: "teams" | "contributors";
   generatedAt: string;
-  githubActionsCiEnabled?: boolean;
   items: ProductivityInsightsNeedsAttentionItemDto[];
 }
 
@@ -1107,3 +1084,13 @@ export interface HrisTriggerSyncResultDto {
   /** Per-provider results when one or more HRIS sources are configured. */
   providers?: HrisProviderSyncResultDto[];
 }
+
+export {
+  JOURNEY_STEP_IDS,
+  JOURNEY_STEP_REGISTRY,
+  normalizeStepIdList,
+  normalizeToStepId,
+  parseJourneyStepInputs,
+  stepIdToRoute,
+  type JourneyStepId,
+} from "./journeySteps.js";

package/src/journeySteps.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for journey step ID registry and normalization.
+ */
+import {
+  JOURNEY_STEP_IDS,
+  normalizeStepIdList,
+  normalizeToStepId,
+  parseJourneyStepInputs,
+  stepIdToRoute,
+} from "./journeySteps.js";
+
+if (normalizeToStepId("/phase-a/p1") !== "onboarding.workspace") {
+  throw new Error("expected /phase-a/p1 → onboarding.workspace");
+}
+if (normalizeToStepId("/onboarding/workspace") !== "onboarding.workspace") {
+  throw new Error("expected semantic route alias");
+}
+if (normalizeToStepId("readiness.dashboard") !== "readiness.dashboard") {
+  throw new Error("expected canonical step id passthrough");
+}
+if (normalizeToStepId("/unknown/route") !== null) {
+  throw new Error("unknown route should normalize to null");
+}
+
+const deduped = normalizeStepIdList(["/phase-a/p1", "/onboarding/workspace", "/phase-a/p1"]);
+if (deduped.length !== 1 || deduped[0] !== "onboarding.workspace") {
+  throw new Error(`dedupe failed: ${JSON.stringify(deduped)}`);
+}
+
+const droppedUnknown = parseJourneyStepInputs(["/phase-a/p1", "/stale/route"]);
+if (droppedUnknown.error || droppedUnknown.value?.length !== 1) {
+  throw new Error(`unknown should drop silently by default: ${JSON.stringify(droppedUnknown)}`);
+}
+if (droppedUnknown.unknown?.length !== 1 || droppedUnknown.unknown[0] !== "/stale/route") {
+  throw new Error("unknown list should report dropped entries");
+}
+
+const rejectUnknown = parseJourneyStepInputs(["/stale/route"], { rejectUnknown: true });
+if (rejectUnknown.error !== "Unknown journey step" || rejectUnknown.unknown?.[0] !== "/stale/route") {
+  throw new Error(`rejectUnknown failed: ${JSON.stringify(rejectUnknown)}`);
+}
+
+const blankStep = parseJourneyStepInputs(["   "], { rejectUnknown: true });
+if (blankStep.error !== "Each completed step must be a non-empty string") {
+  throw new Error(`blank step guard failed: ${JSON.stringify(blankStep)}`);
+}
+
+const atCap = parseJourneyStepInputs(JOURNEY_STEP_IDS, { rejectUnknown: true });
+if (atCap.error || atCap.value?.length !== JOURNEY_STEP_IDS.length) {
+  throw new Error(`full registry parse failed: ${JSON.stringify(atCap)}`);
+}
+
+if (stepIdToRoute("onboarding.workspace") !== "/onboarding/workspace") {
+  throw new Error("stepIdToRoute failed for onboarding.workspace");
+}
+if (stepIdToRoute("not.a.step") !== null) {
+  throw new Error("stepIdToRoute should return null for unknown id");
+}
+
+console.log("journeySteps.test: OK");

package/src/journeySteps.ts

@@ -0,0 +1,190 @@
+/**
+ * Canonical journey step IDs — stable keys for journey progress storage.
+ * Semantic routes are the SPA URL surface; legacy /phase-* paths normalize here.
+ */
+
+export const JOURNEY_STEP_IDS = [
+  "onboarding.workspace",
+  "onboarding.ai_readiness",
+  "onboarding.integrations",
+  "readiness.dashboard",
+  "readiness.fix_queue",
+  "readiness.activity",
+  "insights.productivity",
+  "insights.productivity.by_user",
+  "insights.productivity.by_team",
+  "insights.ai_usage",
+  "insights.ai_usage.by_user",
+  "insights.ai_usage.by_team",
+  "insights.ai_usage.by_model",
+] as const;
+
+export type JourneyStepId = (typeof JOURNEY_STEP_IDS)[number];
+
+type StepDef = {
+  id: JourneyStepId;
+  route: string;
+  aliases: readonly string[];
+};
+
+/** Registry order matches product journey A → R → C. */
+export const JOURNEY_STEP_REGISTRY: readonly StepDef[] = [
+  {
+    id: "onboarding.workspace",
+    route: "/onboarding/workspace",
+    aliases: ["/phase-a/p1"],
+  },
+  {
+    id: "onboarding.ai_readiness",
+    route: "/onboarding/ai-readiness",
+    aliases: ["/phase-a/p2"],
+  },
+  {
+    id: "onboarding.integrations",
+    route: "/onboarding/integrations",
+    aliases: [
+      "/onboarding/platform",
+      "/phase-a/p3",
+      "/phase-a/p4",
+      "/phase-a/p5",
+      "/phase-a/p6",
+      "/phase-a/p7",
+    ],
+  },
+  {
+    id: "readiness.dashboard",
+    route: "/agentic-foundation",
+    aliases: ["/phase-r/r1"],
+  },
+  {
+    id: "readiness.fix_queue",
+    route: "/agentic-foundation/fix-queue",
+    aliases: ["/phase-r/r3"],
+  },
+  {
+    id: "readiness.activity",
+    route: "/agentic-foundation/activity",
+    aliases: ["/phase-r/r4"],
+  },
+  {
+    id: "insights.productivity",
+    route: "/insights/productivity",
+    aliases: ["/insights/productivity/overview", "/phase-c/c4"],
+  },
+  {
+    id: "insights.productivity.by_user",
+    route: "/insights/productivity/by-user",
+    aliases: ["/phase-c/c4/by-user"],
+  },
+  {
+    id: "insights.productivity.by_team",
+    route: "/insights/productivity/by-team",
+    aliases: ["/phase-c/c4/by-team"],
+  },
+  {
+    id: "insights.ai_usage",
+    route: "/insights/ai-usage",
+    aliases: ["/insights/ai-usage/overview", "/phase-c/c7"],
+  },
+  {
+    id: "insights.ai_usage.by_user",
+    route: "/insights/ai-usage/by-user",
+    aliases: ["/phase-c/c7/ai-usage-by-user"],
+  },
+  {
+    id: "insights.ai_usage.by_team",
+    route: "/insights/ai-usage/by-team",
+    aliases: ["/phase-c/c7/ai-usage-by-team"],
+  },
+  {
+    id: "insights.ai_usage.by_model",
+    route: "/insights/ai-usage/by-model",
+    aliases: ["/phase-c/c7/costs-by-llm-model"],
+  },
+] as const;
+
+const STEP_ID_SET = new Set<string>(JOURNEY_STEP_IDS);
+
+const ALIAS_TO_STEP_ID = new Map<string, JourneyStepId>();
+
+for (const def of JOURNEY_STEP_REGISTRY) {
+  ALIAS_TO_STEP_ID.set(def.id, def.id);
+  ALIAS_TO_STEP_ID.set(def.route, def.id);
+  for (const alias of def.aliases) {
+    ALIAS_TO_STEP_ID.set(alias, def.id);
+  }
+}
+
+const STEP_ID_TO_ROUTE = new Map<JourneyStepId, string>(
+  JOURNEY_STEP_REGISTRY.map((d) => [d.id, d.route]),
+);
+
+function normalizePathKey(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return "";
+  const noQuery = trimmed.split("?")[0]?.split("#")[0] ?? trimmed;
+  const collapsed = noQuery.replace(/\/+$/, "") || "/";
+  return collapsed;
+}
+
+/** Map step ID, semantic route, or legacy path to a canonical step ID. */
+export function normalizeToStepId(input: string): JourneyStepId | null {
+  const key = normalizePathKey(input);
+  if (!key) return null;
+  return ALIAS_TO_STEP_ID.get(key) ?? null;
+}
+
+/** Resolve a canonical step ID to its primary semantic SPA route. */
+export function stepIdToRoute(stepId: string): string | null {
+  if (!STEP_ID_SET.has(stepId)) return null;
+  return STEP_ID_TO_ROUTE.get(stepId as JourneyStepId) ?? null;
+}
+
+/** Normalize an array of mixed inputs to deduped canonical step IDs (drops unknowns). */
+export function normalizeStepIdList(inputs: readonly string[]): JourneyStepId[] {
+  const out = new Set<JourneyStepId>();
+  for (const raw of inputs) {
+    const id = normalizeToStepId(raw);
+    if (id) out.add(id);
+  }
+  return [...out];
+}
+
+/** Accept step IDs and legacy/route strings; returns normalized IDs or an error message. */
+export function parseJourneyStepInputs(
+  inputs: readonly string[],
+  options?: { rejectUnknown?: boolean },
+): { value?: JourneyStepId[]; error?: string; unknown?: string[] } {
+  const rejectUnknown = options?.rejectUnknown === true;
+  const unknown: string[] = [];
+  const out = new Set<JourneyStepId>();
+  for (const raw of inputs) {
+    if (typeof raw !== "string") {
+      return { error: "Each completed step must be a string" };
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      return { error: "Each completed step must be a non-empty string" };
+    }
+    if (trimmed.length > 128) {
+      return { error: "Each completed step must be at most 128 characters" };
+    }
+    const id = normalizeToStepId(trimmed);
+    if (!id) {
+      unknown.push(trimmed);
+      continue;
+    }
+    out.add(id);
+  }
+  if (rejectUnknown && unknown.length > 0) {
+    return { error: "Unknown journey step", unknown };
+  }
+  const value = [...out];
+  if (value.length > 256) {
+    return { error: "completedStepIds must have at most 256 entries" };
+  }
+  if (unknown.length > 0) {
+    return { value, unknown };
+  }
+  return { value };
+}