Assessor_2.0/src/api/assessor-api-contract.ts

import type { Assessment, ScanRun } from '../domain/canonical-model';
import type { ReimportReviewTransferSummary } from '../domain/reimport-review-transfer';
import type { ImportBatchPreview, ImportBatchSelection, ImportFingerprint } from '../domain/import-workflow';
import type { MicrosoftSecurityBaselineRecord, MicrosoftSecurityBaselineSelection } from '../domain/microsoft-security-baseline';
import type { StoredMicrosoftSecurityBaselineAnalysis } from '../domain/microsoft-security-baseline-analysis';
import type { StoredGpoPolicyAnalysis } from '../domain/gpo-analysis-persistence';
import type {
  CreateEnvironmentProfileRequest,
  CreatePolicySnapshotAggregationRequest,
  EnvironmentProfile,
  StoredPolicySnapshotAggregation
} from '../domain/gpo-snapshot-aggregation';
export type { DbStructureResponse } from '../domain/db-structure';
import type { CreatePolicyEvaluationRequest, StoredPolicyEvaluation } from '../domain/policy-evaluation';
import type { CreatePolicyFindingRunRequest, StoredPolicyFindingRun } from '../domain/policy-finding';
import type { PolicyEvaluationRuleCatalog } from '../domain/policy-evaluation-rules';
import type { PolicyAnalysisOverview } from '../domain/policy-analysis-overview';
import type { CveEnrichmentRecord } from '../domain/cve-enrichment';
export type { AiOverviewCreateRequest, AiOverviewResponse } from '../domain/ai-overview';
export type {
  RegulatoryMappingCreateRequest,
  RegulatoryMappingDecisionCreateRequest,
  RegulatoryMappingResponse
} from '../domain/regulatory-mapping';
export const ASSESSOR_API_PREFIX = '/api/v1';
export const ASSESSOR_MUTATION_HEADER = 'X-Assessor-Request';

export interface AssessorHealthResponse {
  status: 'ok';
  application: 'ASSESSOR';
  productVersion: string;
  apiVersion: 1;
  releaseId?: string;
  developmentInstanceId?: string;
  repositoryRevision: number;
  persistence: 'memory' | 'postgresql';
}

export interface AssessorApiErrorBody {
  error: {
    code: string;
    message: string;
    requestId: string;
  };
}

export interface CveEnrichmentResponse { version: 1; record: CveEnrichmentRecord; }

export interface ImportSourceValidationRequest {
  fileName: string;
  sizeBytes: number;
}

export interface ImportSourceValidationResponse {
  accepted: true;
  format: 'CSV' | 'JSON' | 'XML' | 'HTML' | 'XLSX' | 'XLS';
  maximumSizeBytes: number;
}

export interface ImportSourceParseRequest {
  fileName: string;
  sizeBytes: number;
  lastModified: number;
  mediaType?: string;
  bytesBase64: string;
  delimiter?: string;
}
export interface ImportBatchPreviewRequest {
  files: ImportSourceParseRequest[];
  targetProjectId?: string;
  targetAssessmentId?: string;
  replacesScanRunId?: string;
}

export interface ImportBatchCompleteRequest {
  batchId: string;
  entries: ImportBatchSelection[];
  targetProjectId?: string;
  targetAssessmentId?: string;
  replacesScanRunId?: string;
}

export interface ImportBatchCompleteResponse {
  batchId: string;
  fingerprints: ImportFingerprint[];
  repositoryRevision: number;
  projectId: string;
  assessmentId: string;
  scanRunId: string;
  replacedScanRunId?: string;
  importedFiles: number;
  importedOccurrences: number;
  reimportReviewTransfer?: ReimportReviewTransferSummary;
}

export interface GpoBackupSubmissionRequest {
  fileName: string;
  sizeBytes: number;
  bytesBase64: string;
  assessmentId?: string;
}

export interface GpoBackupSubmissionResponse {
  version: 1;
  artifactId: string;
  jobId: string;
  sha256: string;
  sizeBytes: number;
  status: 'queued';
  deduplicated: boolean;
  repositoryRevision: number;
}
export interface GpoBackupRetryResponse {
  version: 1;
  artifactId: string;
  jobId: string;
  status: 'queued';
  attempts: number;
}

export interface GpoBackupDeleteResponse {
  version: 1;
  artifactId: string;
  deleted: true;
  storageRemoval: 'complete' | 'pending';
}
export interface GpoBackupReprocessResponse {
  version: 1;
  artifactId: string;
  jobId: string;
  status: 'queued' | 'running' | 'succeeded' | 'dead-letter';
  supersedesProcessingRunId: string;
}
export type GpoBackupDisplayState = 'queued' | 'running' | 'succeeded' | 'partial' | 'dead-letter' | 'recovery-required';

export interface GpoBackupStatusRecord {
  version: 1;
  artifactId: string;
  assessmentId?: string;
  jobId?: string;
  fileName: string;
  sizeBytes: number;
  submittedAt: string;
  updatedAt: string;
  state: GpoBackupDisplayState;
  attempts: number;
  maxAttempts: number;
  lastErrorCode?: string;
  processingStatus?: 'complete' | 'partial' | 'failed';
  completedAt?: string;
  /** Number of individual GPOs detected inside this one uploaded tenant backup snapshot. */
  gpoCount: number;
  /** @deprecated Compatibility alias for gpoCount; it never counts tenant backup snapshots. */
  backupInstanceCount: number;
}

export interface ProjectAssessmentHistoryResponse {
  version: 1;
  projectId: string;
  assessments: Assessment[];
  scanRuns: ScanRun[];
}

export interface GpoBackupStatusResponse {
  version: 1;
  projectId: string;
  generatedAt: string;
  records: GpoBackupStatusRecord[];
}
export interface MicrosoftSecurityBaselineListResponse { version: 1; records: MicrosoftSecurityBaselineRecord[]; }
export type PolicyEvaluationCreateRequest = CreatePolicyEvaluationRequest;
export interface PolicyEvaluationResponse { version: 1; record: StoredPolicyEvaluation; }
export interface PolicyEvaluationListResponse { version: 1; projectId: string; records: StoredPolicyEvaluation[]; }
export type PolicyFindingRunCreateRequest = CreatePolicyFindingRunRequest;
export interface PolicyFindingRunResponse { version: 1; record: StoredPolicyFindingRun; }
export interface PolicyFindingRunListResponse { version: 1; projectId: string; records: StoredPolicyFindingRun[]; }
export type PolicyAnalysisOverviewResponse = PolicyAnalysisOverview;
export interface PolicyEvaluationRuleCatalogResponse { version: 1; catalog: PolicyEvaluationRuleCatalog; }
export interface MicrosoftSecurityBaselineSubmissionResponse { version: 1; record: MicrosoftSecurityBaselineRecord; }
export interface MicrosoftSecurityBaselineDeletionResponse { version: 1; record: MicrosoftSecurityBaselineRecord; }
export interface MicrosoftSecurityBaselineAnalysisResponse { version: 1; record: StoredMicrosoftSecurityBaselineAnalysis; }
export interface MicrosoftSecurityBaselineAnalysisListResponse { version: 1; records: StoredMicrosoftSecurityBaselineAnalysis[]; }
export interface GpoPolicyAnalysisListResponse { version: 1; projectId: string; records: StoredGpoPolicyAnalysis[]; }
export type EnvironmentProfileCreateRequest = CreateEnvironmentProfileRequest;
export interface EnvironmentProfileResponse { version: 1; record: EnvironmentProfile; }
export interface EnvironmentProfileListResponse { version: 1; projectId: string; records: EnvironmentProfile[]; }
export type PolicySnapshotAggregationCreateRequest = CreatePolicySnapshotAggregationRequest;
export interface PolicySnapshotAggregationResponse { version: 1; record: StoredPolicySnapshotAggregation; }
export interface PolicySnapshotAggregationListResponse { version: 1; projectId: string; records: StoredPolicySnapshotAggregation[]; }
export type MicrosoftSecurityBaselineSelectionResponse = MicrosoftSecurityBaselineSelection;

export type ImportBatchPreviewResponse = ImportBatchPreview;