TypeScript Types

/**
 * Brain Spec v1 — Standard types.
 *
 * Generalized from Anatole types (same shape, no prefix).
 * Any client implementing Brain Spec v1 returns these types.
 */

// -- Envelope --

export interface BrainApiEnvelope<T> {
  version: string;
  lastUpdated: string;
  checksum: string;
  data: T;
}

// -- Manifest --

export interface BrainManifest {
  specVersion: string;
  productName: string;
  productSlug: string;
  availableEndpoints: string[];
}

// -- Product Brain (7 types) --

export interface ProductCapability {
  id: string;
  slug: string;
  name: string;
  category: string;
  summary: string;
  description: string;
  status: "available" | "partial" | "not_available" | "deprecated";
  available: boolean;
  supportedPlans: string[];
  supportedPersonas: string[];
  relatedUseCaseIds: string[];
  relatedDemoIds: string[];
  limitations: string[];
  caveats: string[];
  proofRefs: string[];
  faqAnswerIds: string[];
  tags: string[];
  lastVerifiedAt: string;
  version: string;
}

export interface ProductLimitation {
  id: string;
  capabilityId?: string;
  title: string;
  description: string;
  limitationType: string;
  severity: "info" | "important" | "critical";
  escalationRequired: boolean;
  lastVerifiedAt: string;
  version: string;
}

export interface SalesFaqAnswer {
  id: string;
  canonicalQuestion: string;
  questionType: string;
  approvedAnswer: string;
  answerMode: "strict" | "contextual";
  escalationRequired: boolean;
  relatedCapabilityIds: string[];
  relatedLimitationIds: string[];
  relatedDemoIds: string[];
  tags: string[];
  owner: string;
  lastReviewedAt: string;
  version: string;
}

export interface UseCaseMapping {
  id: string;
  personaSlug: string;
  useCaseSlug: string;
  useCaseTitle: string;
  useCaseDescription: string;
  painPoints: string[];
  recommendedCapabilityIds: string[];
  recommendedDemoIds: string[];
  recommendedCTA: string;
  version: string;
}

export interface DemoAsset {
  id: string;
  slug: string;
  title: string;
  description: string;
  supademoUrl: string;
  language: string;
  personaTargets: string[];
  useCaseSlugs: string[];
  relatedCapabilityIds: string[];
  estimatedDurationSeconds: number;
  priority: number;
  isActive: boolean;
  version: string;
}

export interface PlanRule {
  id: string;
  planSlug: string;
  planName: string;
  includedCapabilityIds: string[];
  excludedCapabilityIds: string[];
  limitations: string[];
  version: string;
}

export interface ApprovedNarrative {
  id: string;
  narrativeType: string;
  title: string;
  audience: string[];
  body: string;
  relatedCapabilityIds: string[];
  version: string;
  lastReviewedAt: string;
}

// -- Code Brain (5 types) --

export interface CapabilityAssertionSpec {
  id: string;
  capabilityId: string;
  capabilitySlug: string;
  status: "available" | "partial" | "unsupported" | "deprecated";
  confidence: "high" | "medium" | "low";
  technicalEvidence: {
    modules: string[];
    apiRoutes: string[];
    dataModels: string[];
    featureFlags?: string[];
    adminScreens?: string[];
  };
  limitations: string[];
  notes?: string;
  verifiedBy: string;
  lastVerifiedAt: string;
  version: string;
}

export interface ApiSurfaceItemSpec {
  id: string;
  route: string;
  method: string;
  description: string;
  auth: string;
  relatedCapabilityIds: string[];
  tags: string[];
  version: string;
}

export interface DataModelItem {
  id: string;
  name: string;
  description: string;
  fields: string[];
  relations?: string[];
  relatedCapabilityIds: string[];
  tags: string[];
  version: string;
}

export interface ModuleMapItem {
  id: string;
  modulePath: string;
  moduleName: string;
  purpose: string;
  relatedCapabilityIds: string[];
  tags: string[];
  version: string;
}

export interface ReleaseNote {
  id: string;
  version: string;
  releaseDate: string;
  changes: string[];
  affectedCapabilityIds: string[];
  notes?: string;
}

// -- Aggregated data --

export interface ProductBrainData {
  capabilities: ProductCapability[];
  limitations: ProductLimitation[];
  faq: SalesFaqAnswer[];
  useCaseMappings: UseCaseMapping[];
  demoCatalog: DemoAsset[];
  planRules: PlanRule[];
  narratives: ApprovedNarrative[];
}

export interface CodeBrainData {
  capabilityAssertions: CapabilityAssertionSpec[];
  apiSurface: ApiSurfaceItemSpec[];
  dataModelMap: DataModelItem[];
  moduleMap: ModuleMapItem[];
  releaseNotes: ReleaseNote[];
}

export interface BrainSyncData {
  manifest: BrainManifest;
  productBrain: ProductBrainData;
  codeBrain: CodeBrainData;
  fetchedAt: string;
}