@thinkai/tai-api-contract 1.0.0

package/src/index.ts

@@ -0,0 +1,475 @@
+/**
+ * API contract — shared DTOs and client types.
+ * The ONLY package the frontend may import.
+ */
+export type { Score, Confidence } from "@thinkai/pip-core-types";
+
+/** Run metadata (window, ruleset, created). M5.4: optional tenantId, personId. */
+export interface RunMetadataDto {
+  runId: string;
+  windowStart: string;
+  windowEnd: string;
+  rulesetId: string;
+  rulesetVersion: string;
+  rulesetHash?: string;
+  createdAt?: string;
+  tenantId?: string;
+  personId?: string;
+}
+
+/**
+ * Single score result — metrics, dimension scores, UPI, band. M5.6: optional tenantId, personId.
+ * upi and dimensionScores are in [0, 1] (remapped from internal [-1, 1] for display).
+ * confidence (when present) is evidence-based certainty in [0, 1] for the run and (optionally) dimensions.
+ */
+export interface ScoreDto {
+  runId: string;
+  rulesetId: string;
+  rulesetVersion: string;
+  windowEnd: string;
+  createdAt?: string;
+  tenantId?: string;
+  personId?: string;
+   /** Optional fingerprint of sources config used when this score was computed. */
+  sourcesVersion?: string;
+  metrics: Record<string, number>;
+  dimensionScores: Record<string, number>;
+  upi: number;
+  band: string;
+  /** Scoring confidence (evidence-based). Present when persisted for explainability. */
+  confidence?: SnapshotConfidenceDto;
+  /**
+   * Optional change marker for trend charts.
+   * - 'ruleset' when ruleset version/hash changed since previous point
+   * - 'sources' when sourcesVersion changed since previous point
+   */
+  changeMarker?: "ruleset" | "sources";
+}
+
+/** Paginated list of scores. For sparklines use ?order=asc&limit=31 so items are chronological (oldest first); plot items[].windowEnd vs items[].upi. */
+export interface ScoresHistoryDto {
+  items: ScoreDto[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/** Scoring confidence and gates (for explainability). */
+export interface SnapshotConfidenceDto {
+  overall: number;
+  delivery?: number;
+  quality?: number;
+  impact?: number;
+  collaboration?: number;
+  leverage?: number;
+}
+
+export interface SnapshotGatesDto {
+  dominance: { pass: boolean; maxAbs: number; S_max: number };
+  quality: { pass: boolean; qualityScore: number; theta_q: number; constrained: boolean };
+  confidence: { pass: boolean; confidenceOverall: number; theta_c: number; suppressed: boolean };
+  evidence: { pass: boolean; anyUnknown: boolean; emitIndex: boolean };
+}
+
+/**
+ * Explain: inputs (event IDs) → rules → outputs.
+ * snapshot.upi and snapshot.dimensionScores are in [0, 1] (remapped for display).
+ */
+export interface ExplainDto {
+  runMetadata: RunMetadataDto;
+  snapshot: {
+    runId: string;
+    rulesetId: string;
+    rulesetVersion: string;
+    rulesetHash?: string;
+    metrics: Record<string, number>;
+    dimensionScores: Record<string, number>;
+    upi: number;
+    band: string;
+    /** Expected values used for normalization (m/expected). Present when persisted. */
+    expected?: Record<string, number>;
+    confidence?: SnapshotConfidenceDto;
+    gates?: SnapshotGatesDto;
+  };
+  eventIds: string[];
+}
+
+/**
+ * M6: Provenance graph — traceability chain (score → dimensions → metrics → rules → events). No recomputation.
+ * upi and dimensionScores are in [0, 1] (remapped for display).
+ */
+export interface ProvenanceDto {
+  runId: string;
+  rulesetId: string;
+  rulesetVersion: string;
+  rulesetHash?: string;
+  windowStart: string;
+  windowEnd: string;
+  tenantId?: string;
+  personId?: string;
+  /** Dimension scores (output). */
+  dimensionScores: Record<string, number>;
+  /** Metrics that fed dimension scores. */
+  metrics: Record<string, number>;
+  /** Canonical event IDs that fed this run. */
+  eventIds: string[];
+  upi: number;
+  band: string;
+  /** Scoring confidence (evidence-based). Present when persisted for explainability. */
+  confidence?: SnapshotConfidenceDto;
+  /** Gate results (dominance, quality, confidence, evidence). Present when persisted for explainability. */
+  gates?: SnapshotGatesDto;
+}
+
+/**
+ * M6: Run comparison — why did this score change? (week-over-week deltas, no recomputation).
+ * bandA/bandB are from remapped UPI; delta.dimensionScores and delta.upiDelta are deltas in [0, 1] space.
+ */
+export interface RunComparisonDto {
+  runIdA: string;
+  runIdB: string;
+  windowEndA: string;
+  windowEndB: string;
+  tenantId?: string;
+  personId?: string;
+  /** Deltas (B − A) for metrics and dimensionScores; upiDelta = upiB − upiA (in [0,1] space). */
+  delta: {
+    metrics: Record<string, number>;
+    dimensionScores: Record<string, number>;
+    upiDelta: number;
+  };
+  bandA: string;
+  bandB: string;
+  /** Event IDs only in run A. */
+  eventIdsOnlyInA: string[];
+  /** Event IDs only in run B. */
+  eventIdsOnlyInB: string[];
+  /** Event IDs in both runs. */
+  eventIdsInBoth: string[];
+}
+
+/** Compare view: one entity (person or team) with UPI and optional dimensions/metrics. */
+export interface ComparisonItemDto {
+  id: string;
+  label: string;
+  type: "person" | "team";
+  upi: number | null;
+  band: string | null;
+  dimensionScores?: Record<string, number>;
+  metrics?: Record<string, number>;
+}
+
+/** Response for GET /tenants/:tenantId/compare (side-by-side comparison). */
+export interface ComparisonResponseDto {
+  items: ComparisonItemDto[];
+}
+
+/** M7: Org chart tree node (recursive). */
+export interface OrgChartTreeNodeDto {
+  type?: "org" | "team" | "person";
+  id: string;
+  name?: string;
+  label?: string;
+  children?: OrgChartTreeNodeDto[];
+  person_id?: string;
+  team?: string;
+  role?: string;
+  /** High-level role tag used for stack ranking filters. Defaults to contributor when absent. */
+  roleTag?: "contributor" | "enabler";
+  level?: string;
+  external_ids?: Record<string, string>;
+}
+
+/** Org chart tree node with computed scores (Option B, α=0.2). Used when ?withScores=true. */
+export interface OrgChartTreeNodeWithScoreDto extends OrgChartTreeNodeDto {
+  score?: number | null;
+  individualUpi?: number | null;
+  children?: OrgChartTreeNodeWithScoreDto[];
+}
+
+/** M7: Org chart response (tree only). */
+export interface OrgChartDto {
+  root: OrgChartTreeNodeDto;
+}
+
+/** Summary of a person derived from the tenant's org chart. */
+export interface PersonSummaryDto {
+  /** Canonical person identifier (e.g. work email). */
+  personId: string;
+  team?: string;
+  role?: string;
+  /** High-level role tag used for stack ranking filters. Defaults to contributor when absent. */
+  roleTag?: "contributor" | "enabler";
+  level?: string;
+}
+
+/** Response for GET /tenants/:tenantId/persons (flat list of persons for a tenant). */
+export interface GetTenantPersonsResponseDto {
+  persons: PersonSummaryDto[];
+}
+
+/** Tenant config: per-tenant data source entries (type + params; params may use "env:VAR" for secrets). */
+export interface TenantSourceEntryDto {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Response for POST /tenants/:tenantId/sources/test (test connection; no save). 200 always; success false when connection/auth fails. */
+export interface TestConnectionResponseDto {
+  success: boolean;
+  error?: string;
+}
+
+/** Tenant config response (sources; optionally org chart for Home; optionally region for data residency). */
+export interface TenantConfigDto {
+  sources: TenantSourceEntryDto[];
+  orgChart?: OrgChartDto | null;
+  /** Region for data residency (us, eu, me). Null or absent = legacy/single-region. */
+  region?: string | null;
+}
+
+/** Response for GET /me/tenants: tenants the user is allowed to see (for dropdown). */
+export interface TenantsForUserDto {
+  tenants: { tenantId: string }[];
+}
+
+/** Team member roles exposed to ThinkAI UI. */
+export type TeamMemberRoleDto = "admin" | "editor" | "viewer";
+
+/** Team member row for tenant member management UI. */
+export interface TeamMemberDto {
+  id: string;
+  name: string;
+  email: string;
+  role: TeamMemberRoleDto;
+}
+
+/** Response for GET /tenants/:tenantId/members. */
+export interface TeamMemberListDto {
+  members: TeamMemberDto[];
+}
+
+/** Body for POST /tenants/:tenantId/members/invite. */
+export interface InviteTeamMemberBodyDto {
+  email: string;
+  role: TeamMemberRoleDto;
+}
+
+/** Body for PATCH /tenants/:tenantId/members/:memberId. */
+export interface UpdateTeamMemberRoleBodyDto {
+  role: TeamMemberRoleDto;
+}
+
+/** M6: Single audit log entry (immutable). */
+export interface AuditEntryDto {
+  id: string;
+  timestamp: string;
+  action: string;
+  tenantId?: string;
+  personId?: string;
+  payload: Record<string, unknown>;
+}
+
+/** M6: Paginated audit log. */
+export interface AuditLogListDto {
+  items: AuditEntryDto[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+/** CTO Dashboard: nested metric groups. All fields optional; only present when data exists. */
+export interface DashboardProductivityMetricsDto {
+  velocity?: {
+    avgFirstCommitToPrDays?: number;
+    prsPerDeveloperPerWeek?: number;
+    avgPrMergeTimeHours?: number;
+  };
+  quality?: {
+    codeReviewHoursPerWeek?: number;
+    buildFailuresPerWeek?: number;
+    avgTimeToFixBuildHours?: number;
+    testCoveragePercent?: number;
+    escapedBugsCount?: number;
+    /** Avg cyclomatic complexity (from SonarQube). */
+    complexityAvg?: number;
+    /** Code smells count (from SonarQube). */
+    codeSmellsCount?: number;
+    /** Total violations count (from SonarQube). */
+    violationsCount?: number;
+  };
+  process?: {
+    planningTimeHoursPerWeek?: number;
+    contextSwitchingOverheadPercent?: number;
+  };
+  aiAdoption?: {
+    aiToolUsageRatePercent?: number;
+    aiAssistedContributionRatioPercent?: number;
+  };
+  readiness?: {
+    engineeringProcessReadinessPercent?: number;
+  };
+  /** Flow Framework metrics: flow time, flow load, flow efficiency. */
+  flow?: {
+    /** Median flow time in days (work started → completed); ticket or PR lifecycle. */
+    flowTimeDays?: number;
+    /** Average work-in-progress (WIP) count in window. */
+    flowLoad?: number;
+    /** Active work time / total flow time (0–100). Undefined when no wait/active data. */
+    flowEfficiencyPercent?: number;
+  };
+  /** DORA metrics: deployment frequency, lead time for changes, change failure rate, MTTR. See docs/DORA-Event-Attributes.md and docs/DORA-Benchmark-Bands.md. */
+  dora?: {
+    /** Deployments per week (production when environment present; else all). */
+    deploymentFrequencyPerWeek?: number;
+    /** DORA benchmark band for deployment frequency. See docs/DORA-Benchmark-Bands.md. */
+    deploymentFrequencyBand?: "elite" | "high" | "medium" | "low";
+    /** Median time from code change to production (hours). */
+    leadTimeForChangesHours?: number;
+    /** DORA benchmark band for lead time. See docs/DORA-Benchmark-Bands.md. */
+    leadTimeForChangesBand?: "elite" | "high" | "medium" | "low";
+    /** % of deployments causing incidents (or proxy: incidents / deployments). */
+    changeFailureRatePercent?: number;
+    /** DORA benchmark band for change failure rate. See docs/DORA-Benchmark-Bands.md. */
+    changeFailureRateBand?: "elite" | "high" | "medium" | "low";
+    /** Median time from incident.declared to incident.resolved (hours). */
+    meanTimeToRecoveryHours?: number;
+    /** DORA benchmark band for MTTR. See docs/DORA-Benchmark-Bands.md. */
+    meanTimeToRecoveryBand?: "elite" | "high" | "medium" | "low";
+  };
+  /** Resource allocation: how engineering time is distributed across work types. Percentages are 0–100 and typically sum to ~100. */
+  allocation?: {
+    /** Share of work attributed to roadmap/features (tickets and PRs not classified as maintenance/incidents/support). */
+    featurePercent?: number;
+    /** Share of work attributed to maintenance and tech debt reduction (when classification rules mark work as tech_debt). */
+    techDebtPercent?: number;
+    /** Share of work attributed to incident response (incidents, firefighting, production issues). */
+    incidentPercent?: number;
+    /** Share of work attributed to support/helpdesk/customer support-style work (when classification rules mark work as support). */
+    supportPercent?: number;
+    /** Share of work that does not fall into the above categories (uncategorized/other). */
+    otherPercent?: number;
+  };
+  /**
+   * Cycle time breakdown: per-person segment durations over the selected window.
+   * Stored in dashboard precompute; surfaced via GET /dashboard/cycle-time-breakdown.
+   */
+  cycleTimeBreakdown?: {
+    persons: {
+      personId: string;
+      codingHours?: number;
+      pickupHours?: number;
+      reviewHours?: number;
+      deployHours?: number;
+      totalHours?: number;
+      bottleneckSegment?: "coding" | "pickup" | "review" | "deploy";
+    }[];
+  };
+}
+
+/** Single per-person cycle time breakdown item for the CTO dashboard. Durations are in hours over the selected window. */
+export interface CycleTimeBreakdownItemDto {
+  /** Canonical person identifier (e.g. work email). */
+  personId: string;
+  /** Human-readable label (e.g. name from org chart). */
+  label?: string;
+  /** Optional team label from org chart or person summary. */
+  team?: string;
+  /** Average time spent in the Coding segment (first commit/branch → PR opened), in hours. */
+  codingHours?: number;
+  /** Average time spent waiting for review (PR opened → first review), in hours. */
+  pickupHours?: number;
+  /** Average time spent in active review (first review → PR approved/merged), in hours. */
+  reviewHours?: number;
+  /** Average time from merge to deploy success, in hours. */
+  deployHours?: number;
+  /** Total average cycle time (sum of defined segment durations), in hours. */
+  totalHours?: number;
+  /** Segment contributing the largest share of total cycle time. */
+  bottleneckSegment?: "coding" | "pickup" | "review" | "deploy";
+}
+
+/** CTO Dashboard: precomputed cycle time breakdown per tenant/scope/window. */
+export interface CycleTimeBreakdownDto {
+  tenantId: string;
+  windowStart: string;
+  windowEnd: string;
+  scope: "org" | "team" | "person";
+  items: CycleTimeBreakdownItemDto[];
+}
+
+/** CTO Dashboard: response for GET /tenants/:tenantId/dashboard/productivity */
+export interface DashboardProductivityDto {
+  tenantId: string;
+  windowStart: string;
+  windowEnd: string;
+  scope: "org" | "team" | "person";
+  metrics: DashboardProductivityMetricsDto;
+  meta?: { sourceWindow?: string; computedAt?: string };
+}
+
+/** CTO Dashboard: time-series for GET /tenants/:tenantId/dashboard/productivity/history */
+export interface DashboardProductivityHistoryDto {
+  buckets: {
+    bucketStart: string;
+    bucketEnd: string;
+    metrics: DashboardProductivityMetricsDto;
+  }[];
+}
+
+/** Appeal: user contests a misattributed event. Lifecycle: pending → approved | rejected. */
+export interface AppealDto {
+  id: string;
+  tenantId: string;
+  personId: string;
+  eventId: string;
+  reason?: string | null;
+  status: "pending" | "approved" | "rejected";
+  createdAt: string;
+  resolvedAt?: string | null;
+  resolvedBy?: string | null;
+}
+
+/** Body for POST /tenants/:tenantId/appeals (submit appeal). */
+export interface CreateAppealDto {
+  eventId: string;
+  reason?: string | null;
+}
+
+/** Feedback: general scoring concerns or rules review requests. For admin review; distinct from appeals. */
+export interface FeedbackDto {
+  id: string;
+  tenantId: string;
+  personId: string;
+  category: "scoring_concern" | "rules_review";
+  message: string;
+  personIdContext?: string | null;
+  createdAt: string;
+}
+
+/** Body for POST /tenants/:tenantId/feedback (submit feedback). */
+export interface CreateFeedbackDto {
+  category: "scoring_concern" | "rules_review";
+  message: string;
+  personIdContext?: string | null;
+}
+
+/** Export API: single event for JSON export (GET /tenants/:tenantId/export?type=events&format=json). */
+export interface ExportEventDto {
+  eventId: string;
+  tenantId: string;
+  occurredAt: string;
+  source: string;
+  eventType: string;
+  entityRefs?: { kind: string; id: string }[];
+  attributes: Record<string, unknown>;
+}
+
+/** Export API: events JSON response. */
+export interface ExportEventsResponseDto {
+  items: ExportEventDto[];
+  total: number;
+}
+
+/** OpenAPI path and operation typings (generated from `openapi/openapi.yaml`). */
+export type { paths, operations } from "./generated/openapi.js";