@thinkai/tai-api-contract 2.34.0 → 2.35.0

package/src/generated/openapi.ts

@@ -395,7 +395,7 @@ export interface paths {
         };
         /**
          * Productivity insights — contributor drilldown
-         * @description Weekly and daily activity rollups for a single contributor on `/phase-c/c4/contributors/:id`. Distributes weekly merged PR counts from precomputed person metrics across weekdays; includes fail-rate signals and period-over-period summary deltas. Accepts org-chart person ids (typically email) and synthetic GitHub scopes (`__github:{login}`) for contributors not in the org chart.
+         * @description Weekly and daily activity rollups for a single contributor on `/insights/productivity/contributors/:loginOrId`. Accepts GitHub login slugs (preferred public URL), org-chart person ids (typically email), and synthetic GitHub scopes (`__github:{login}`) for contributors not in the org chart.
          */
         get: operations["getProductivityInsightsContributor"];
         put?: never;
@@ -642,7 +642,7 @@ export interface paths {
         put?: never;
         /**
          * Create GitHub App installation URL
-         * @description Creates a GitHub App installation URL scoped to the workspace and caller. Body is optional; when omitted, defaults to `/phase-a/p4` return path. Optional `pickerSession` (from user OAuth org picker) recovers `returnPath` from the server-side picker snapshot when the multi-hop authorize→install flow should return to the page where OAuth started.
+         * @description Creates a GitHub App installation URL scoped to the workspace and caller. Body is optional; when omitted, defaults to `/onboarding/integrations` return path. Optional `pickerSession` (from user OAuth org picker) recovers `returnPath` from the server-side picker snapshot when the multi-hop authorize→install flow should return to the page where OAuth started.
          */
         post: operations["postGithubInstallUrl"];
         delete?: never;
@@ -1121,6 +1121,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/readiness/repos/by-slug/{providerSlug}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Single repo readiness by provider slug
+         * @description Returns one stored repository scorecard keyed by `providerSlug` (`owner/repo`). Same response as `GET .../readiness/repos/{repoId}`. Unknown slug returns `404`.
+         */
+        get: operations["getReadinessRepoBySlug"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/readiness/repos/{repoId}": {
         parameters: {
             query?: never;
@@ -1901,7 +1921,7 @@ export interface paths {
         };
         /**
          * Workspace journey step completion
-         * @description Returns the workspace-scoped journey progress state. Returns an empty `completedSteps` list with a synthetic `updatedAt` if no row exists yet. Covers issue #271.
+         * @description Returns the workspace-scoped journey progress state. Returns an empty `completedStepIds` array when no row exists yet (updatedAt is synthetic in that case). Values are canonical step IDs (see `JourneyStepId`); legacy route strings are accepted on PUT and normalized. Covers issue #271.
          */
         get: operations["getYourAiJourneyProgress"];
         /**
@@ -3763,14 +3783,31 @@ export interface components {
         AiStrategyPlanDto: {
             phases: components["schemas"]["AiStrategyPhaseBlockDto"][];
         };
+        /**
+         * @description Canonical journey step identifier (stable across URL reshuffles).
+         * @enum {string}
+         */
+        JourneyStepId: "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";
         JourneyProgressDto: {
-            completedSteps: string[];
+            /** @description Canonical completed journey step IDs. */
+            completedStepIds: components["schemas"]["JourneyStepId"][];
+            /**
+             * @deprecated
+             * @description Deprecated alias of completedStepIds (legacy clients). Omitted on new responses when empty.
+             */
+            completedSteps?: string[];
             /** Format: date-time */
             updatedAt: string;
         };
         JourneyProgressUpdateDto: {
-            completedSteps: string[];
-        };
+            /** @description Idempotent replace-all of completed step IDs. */
+            completedStepIds?: components["schemas"]["JourneyStepId"][];
+            /**
+             * @deprecated
+             * @description Deprecated input alias — route strings and legacy `/phase-*` paths are normalized to step IDs.
+             */
+            completedSteps?: string[];
+        } | unknown | unknown;
         /** @enum {string} */
         ThemePreference: "light" | "dark" | "system";
         NotificationPreferencesDto: {
@@ -3892,7 +3929,9 @@ export interface components {
             /** Format: date-time */
             windowEnd: string;
             journey: {
-                completedSteps: string[];
+                completedStepIds: components["schemas"]["JourneyStepId"][];
+                /** @deprecated */
+                completedSteps?: string[];
                 /** Format: date-time */
                 updatedAt: string | null;
             };
@@ -4215,6 +4254,8 @@ export interface components {
     parameters: {
         WorkspaceId: string;
         RepoId: string;
+        /** @description Provider repository slug in `owner/repo` form (GitHub). Used for shareable public URLs; resolves to the same row as `repoId` UUID internally. */
+        ProviderSlug: string;
         ProjectId: string;
         NotificationId: string;
         /** @description Workspace member user id (`tai_users.id`). */
@@ -4424,6 +4465,7 @@ export type AiStrategyRecommendBodyDto = components['schemas']['AiStrategyRecomm
 export type AiStrategyTaskRecommendationDto = components['schemas']['AiStrategyTaskRecommendationDto'];
 export type AiStrategyPhaseBlockDto = components['schemas']['AiStrategyPhaseBlockDto'];
 export type AiStrategyPlanDto = components['schemas']['AiStrategyPlanDto'];
+export type JourneyStepId = components['schemas']['JourneyStepId'];
 export type JourneyProgressDto = components['schemas']['JourneyProgressDto'];
 export type JourneyProgressUpdateDto = components['schemas']['JourneyProgressUpdateDto'];
 export type ThemePreference = components['schemas']['ThemePreference'];
@@ -4461,6 +4503,7 @@ export type ResponseUnauthorized = components['responses']['Unauthorized'];
 export type ResponseForbidden = components['responses']['Forbidden'];
 export type ParameterWorkspaceId = components['parameters']['WorkspaceId'];
 export type ParameterRepoId = components['parameters']['RepoId'];
+export type ParameterProviderSlug = components['parameters']['ProviderSlug'];
 export type ParameterProjectId = components['parameters']['ProjectId'];
 export type ParameterNotificationId = components['parameters']['NotificationId'];
 export type ParameterWorkspaceMemberId = components['parameters']['WorkspaceMemberId'];
@@ -5510,7 +5553,7 @@ export interface operations {
             header?: never;
             path: {
                 workspaceId: components["parameters"]["WorkspaceId"];
-                /** @description Org-chart person id or synthetic GitHub scope id (`__github:{login}`). */
+                /** @description GitHub login slug, org-chart person id, or synthetic `__github:{login}` scope id. */
                 contributorId: string;
             };
             cookie?: never;
@@ -7319,6 +7362,50 @@ export interface operations {
             };
         };
     };
+    getReadinessRepoBySlug: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+                /** @description Provider repository slug in `owner/repo` form (GitHub). Used for shareable public URLs; resolves to the same row as `repoId` UUID internally. */
+                providerSlug: components["parameters"]["ProviderSlug"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Repo score */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RepoReadinessScoreDetailDto"];
+                };
+            };
+            /** @description Malformed providerSlug */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Workspace or repository not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     getReadinessRepo: {
         parameters: {
             query?: never;
@@ -8909,7 +8996,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Progress (empty completedSteps when no row exists yet; updatedAt is synthetic in that case) */
+            /** @description Progress (empty completedStepIds when no row exists yet; updatedAt is synthetic in that case) */
             200: {
                 headers: {
                     [name: string]: unknown;

package/src/index.ts

@@ -1084,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 };
+}