/** * API Contract Types for Layer 6 Frontend-Backend Contract Validation * * Prevents frontend-backend authentication mismatches and API contract violations * like the 401 bug that slipped into Shop.Solar production. */ export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'; export type AuthenticationRequirement = 'REQUIRED' | 'OPTIONAL' | 'NONE' | 'FORBIDDEN'; export type AuthState = 'UNAUTHENTICATED' | 'AUTHENTICATED' | 'EXPIRED_TOKEN' | 'INVALID_TOKEN' | 'INSUFFICIENT_PERMISSIONS'; export type AuthMethod = 'SESSION' | 'JWT' | 'API_KEY' | 'BEARER' | 'OAUTH' | 'NONE'; export interface APIContract { readonly endpoint: string; readonly method: HTTPMethod; readonly authentication: AuthenticationRequirement; readonly publicAccess: boolean; readonly authorization?: string[]; readonly requestSchema?: SchemaDefinition; readonly responseSchema?: SchemaDefinition; readonly expectedBehavior: { readonly [K in AuthState]?: ExpectedResponse; }; readonly rateLimit?: RateLimit; readonly description?: string; readonly metadata?: { readonly tags?: string[]; readonly version?: string; readonly deprecated?: boolean; }; } export interface RateLimit { readonly requests: number; readonly window: string; readonly scope: 'IP' | 'USER' | 'API_KEY'; } export interface SchemaDefinition { readonly type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null'; readonly properties?: Record; readonly items?: SchemaDefinition; readonly required?: string[]; readonly pattern?: string; readonly enum?: readonly unknown[]; readonly minimum?: number; readonly maximum?: number; } export interface ExpectedResponse { readonly statusCode: number; readonly bodyPattern?: SchemaDefinition; readonly headers?: Record; readonly errorPattern?: { readonly messageContains?: string; readonly codeEquals?: string | number; }; readonly maxResponseTime?: number; } export interface ContractViolation { readonly contract: APIContract; readonly violationType: ViolationType; readonly severity: 'CRITICAL' | 'ERROR' | 'WARNING' | 'INFO'; readonly message: string; readonly detectedIn: 'FRONTEND' | 'BACKEND' | 'BOTH'; readonly location: string; readonly expected: string; readonly actual: string; readonly suggestedFix: string; readonly autoFixable: boolean; } export type ViolationType = 'AUTH_MISMATCH' | 'AUTH_HEADER_MISSING' | 'ERROR_HANDLING_MISSING' | 'ROLE_VIOLATION' | 'SCHEMA_MISMATCH' | 'METHOD_MISMATCH' | 'ENDPOINT_NOT_FOUND' | 'RATE_LIMIT_UNHANDLED' | 'MISSING_ENDPOINT' | 'MISSING_AUTH_HEADER' | 'WRONG_AUTH_METHOD' | 'ROLE_MISMATCH' | 'UNEXPECTED_STATUS' | 'PERFORMANCE_VIOLATION' | 'CORS_VIOLATION'; export interface APIUsage { readonly filePath: string; readonly lineNumber: number; readonly endpoint: string; readonly method: string; readonly callType: 'fetch' | 'axios' | 'swr' | 'query' | 'mutation'; readonly hasAuthCheck: boolean; readonly includesAuthHeader: boolean; readonly context: 'PUBLIC' | 'PROTECTED' | 'UNKNOWN'; readonly hasErrorHandling: boolean; readonly has401Handler: boolean; readonly has403Handler: boolean; readonly codeSnippet: string; } export interface APIUsageContext { readonly hasAuthCheck: boolean; readonly includesAuthHeader: boolean; readonly context: 'PUBLIC' | 'PROTECTED' | 'UNKNOWN'; readonly hasErrorHandling: boolean; readonly has401Handler: boolean; readonly has403Handler: boolean; } export interface APICall { readonly type: 'fetch' | 'axios' | 'swr' | 'query' | 'mutation'; readonly endpoint: string; readonly method: string; readonly line: number; readonly column?: number; readonly raw: string; } export interface AuthPattern { readonly type: 'SESSION_CHECK' | 'TOKEN_CHECK' | 'HOOK' | 'HOC' | 'MIDDLEWARE'; readonly pattern: RegExp; readonly description: string; } export interface ContractValidationResult { readonly passed: boolean; readonly totalContracts: number; readonly totalViolations: number; readonly violations: ContractViolation[]; readonly criticalCount: number; readonly errorCount: number; readonly warningCount: number; readonly executionTime: number; readonly scannedFiles: number; readonly apiCallsFound: number; } export interface FrontendValidationReport { readonly projectPath: string; readonly timestamp: string; readonly result: ContractValidationResult; readonly summary: string; readonly recommendations: string[]; readonly fixableViolations: number; } export interface BackendFile { readonly path: string; readonly framework: 'nextjs' | 'express' | 'fastify' | 'nestjs' | 'fastapi' | 'django' | 'unknown'; readonly content: string; readonly routeHandler?: RouteHandler; } export interface RouteHandler { readonly name: string; readonly method: HTTPMethod; readonly path: string; readonly authAnalysis: BackendAuthAnalysis; readonly middleware: readonly string[]; } export interface BackendAuthAnalysis { readonly authRequired: boolean; readonly authOptional: boolean; readonly authMethod: AuthMethod; readonly patterns: readonly BackendAuthPattern[]; readonly requiredRoles?: readonly string[]; readonly requiredPermissions?: readonly string[]; } export interface BackendAuthPattern { readonly type: 'SESSION_CHECK' | 'JWT_VERIFY' | 'API_KEY_CHECK' | 'BEARER_TOKEN' | 'MIDDLEWARE'; readonly codeSnippet: string; readonly lineNumber: number; readonly enforcesAuth: boolean; } export interface AuthTestCase { readonly authState: AuthState; readonly expectedStatus: number; readonly expectedBodyPattern?: SchemaDefinition; readonly headers?: Record; readonly body?: unknown; } export interface TestResult { readonly passed: boolean; readonly testCase: AuthTestCase; readonly actualStatus: number; readonly responseBody: unknown; readonly responseHeaders: Record; readonly duration: number; readonly error?: string; readonly suggestedFix?: string; } export interface MatrixResult { readonly testCase: AuthTestCase; readonly passed: boolean; readonly actualStatus: number; readonly message: string; readonly response?: ResponseDetails; readonly violations: readonly ContractViolation[]; } export interface ResponseDetails { readonly statusCode: number; readonly headers: Record; readonly body?: unknown; readonly duration: number; readonly timestamp: string; } export interface RequestDetails { readonly method: HTTPMethod; readonly url: string; readonly headers: Record; readonly body?: unknown; readonly timestamp: string; } export interface APIContractValidationResult { readonly contract: APIContract; readonly passed: boolean; readonly staticAnalysis: { readonly backendFound: boolean; readonly frontendUsages: readonly APIUsage[]; readonly violations: readonly ContractViolation[]; }; readonly runtimeTests: { readonly executed: boolean; readonly testResults: readonly TestResult[]; readonly violations: readonly ContractViolation[]; }; readonly authMatrix: { readonly executed: boolean; readonly matrixResults: readonly MatrixResult[]; readonly violations: readonly ContractViolation[]; }; readonly violations: readonly ContractViolation[]; readonly timestamp: string; readonly executionTime: number; } export interface APIContractSuiteResult { readonly projectName: string; readonly totalContracts: number; readonly passedContracts: number; readonly failedContracts: number; readonly contractResults: readonly APIContractValidationResult[]; readonly allViolations: readonly ContractViolation[]; readonly criticalViolations: number; readonly overallStatus: 'PASSED' | 'FAILED'; readonly timestamp: string; readonly totalExecutionTime: number; } export interface APIContractValidatorConfig { readonly baseUrl?: string; readonly projectPath: string; readonly enableStaticAnalysis: boolean; readonly enableRuntimeTests: boolean; readonly enableAuthMatrix: boolean; readonly testTokens?: { readonly validToken?: string; readonly expiredToken?: string; readonly invalidToken?: string; }; readonly requestTimeout?: number; readonly maxParallelTests?: number; readonly skipSSLVerification?: boolean; readonly customHeaders?: Record; } //# sourceMappingURL=api-contracts.d.ts.map