mcp-wordpress 2.4.2 → 2.5.1

package/src/types/client.ts

@@ -32,15 +32,12 @@ import type {
   UpdateTagRequest,
   UploadMediaRequest,
   UpdateMediaRequest,
+  AuthMethod,
 } from "./wordpress.js";
 
 // Authentication Configuration
-export type AuthMethod =
-  | "app-password"
-  | "jwt"
-  | "basic"
-  | "api-key"
-  | "cookie";
+// AuthMethod is now imported from wordpress.js for consistency
+export type { AuthMethod };
 
 export interface AuthConfig {
   method: AuthMethod;
@@ -54,6 +51,38 @@ export interface AuthConfig {
   clientId?: string;
 }
 
+// Specific credential interfaces for type safety
+export interface AppPasswordCredentials {
+  username: string;
+  appPassword: string;
+}
+
+export interface JwtCredentials {
+  jwtToken: string;
+  username?: string;
+}
+
+export interface BasicCredentials {
+  username: string;
+  password: string;
+}
+
+export interface ApiKeyCredentials {
+  apiKey: string;
+}
+
+// Union type for all credential types
+export type AuthCredentials = AppPasswordCredentials | JwtCredentials | BasicCredentials | ApiKeyCredentials;
+
+// Authentication status interface
+export interface AuthStatus {
+  method: AuthMethod;
+  username?: string | undefined;
+  isAuthenticated: boolean;
+  tokenExpired: boolean;
+  tokenExpiry?: number;
+}
+
 // Client Configuration
 export interface WordPressClientConfig {
   baseUrl: string;
@@ -77,11 +106,11 @@ export interface RequestOptions {
   timeout?: number;
   retries?: number;
   signal?: AbortSignal;
-  params?: any;
+  params?: Record<string, unknown>;
 }
 
 // API Response Wrapper
-export interface APIResponse<T = any> {
+export interface APIResponse<T = unknown> {
   data: T;
   status: number;
   statusText: string;
@@ -120,64 +149,32 @@ export interface IWordPressClient {
   disconnect(): Promise<void>;
 
   // Generic HTTP Methods
-  request<T = any>(
-    method: HTTPMethod,
-    endpoint: string,
-    data?: any,
-    options?: RequestOptions,
-  ): Promise<T>;
-  get<T = any>(endpoint: string, options?: RequestOptions): Promise<T>;
-  post<T = any>(
-    endpoint: string,
-    data?: any,
-    options?: RequestOptions,
-  ): Promise<T>;
-  put<T = any>(
-    endpoint: string,
-    data?: any,
-    options?: RequestOptions,
-  ): Promise<T>;
-  patch<T = any>(
-    endpoint: string,
-    data?: any,
-    options?: RequestOptions,
-  ): Promise<T>;
-  delete<T = any>(endpoint: string, options?: RequestOptions): Promise<T>;
+  request<T = unknown>(method: HTTPMethod, endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+  get<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T>;
+  post<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+  put<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+  patch<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+  delete<T = unknown>(endpoint: string, options?: RequestOptions): Promise<T>;
 
   // Posts
   getPosts(params?: PostQueryParams): Promise<WordPressPost[]>;
-  getPost(
-    id: number,
-    context?: "view" | "embed" | "edit",
-  ): Promise<WordPressPost>;
+  getPost(id: number, context?: "view" | "embed" | "edit"): Promise<WordPressPost>;
   createPost(data: CreatePostRequest): Promise<WordPressPost>;
   updatePost(data: UpdatePostRequest): Promise<WordPressPost>;
-  deletePost(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressPost }>;
+  deletePost(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressPost }>;
   getPostRevisions(id: number): Promise<WordPressPost[]>;
 
   // Pages
   getPages(params?: PostQueryParams): Promise<WordPressPage[]>;
-  getPage(
-    id: number,
-    context?: "view" | "embed" | "edit",
-  ): Promise<WordPressPage>;
+  getPage(id: number, context?: "view" | "embed" | "edit"): Promise<WordPressPage>;
   createPage(data: CreatePageRequest): Promise<WordPressPage>;
   updatePage(data: UpdatePageRequest): Promise<WordPressPage>;
-  deletePage(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressPage }>;
+  deletePage(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressPage }>;
   getPageRevisions(id: number): Promise<WordPressPage[]>;
 
   // Media
   getMedia(params?: MediaQueryParams): Promise<WordPressMedia[]>;
-  getMediaItem(
-    id: number,
-    context?: "view" | "embed" | "edit",
-  ): Promise<WordPressMedia>;
+  getMediaItem(id: number, context?: "view" | "embed" | "edit"): Promise<WordPressMedia>;
   uploadMedia(data: UploadMediaRequest): Promise<WordPressMedia>;
   uploadFile(
     fileData: Buffer,
@@ -187,37 +184,22 @@ export interface IWordPressClient {
     options?: RequestOptions,
   ): Promise<WordPressMedia>;
   updateMedia(data: UpdateMediaRequest): Promise<WordPressMedia>;
-  deleteMedia(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressMedia }>;
+  deleteMedia(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressMedia }>;
 
   // Users
   getUsers(params?: UserQueryParams): Promise<WordPressUser[]>;
-  getUser(
-    id: number | "me",
-    context?: "view" | "embed" | "edit",
-  ): Promise<WordPressUser>;
+  getUser(id: number | "me", context?: "view" | "embed" | "edit"): Promise<WordPressUser>;
   createUser(data: CreateUserRequest): Promise<WordPressUser>;
   updateUser(data: UpdateUserRequest): Promise<WordPressUser>;
-  deleteUser(
-    id: number,
-    reassign?: number,
-  ): Promise<{ deleted: boolean; previous?: WordPressUser }>;
+  deleteUser(id: number, reassign?: number): Promise<{ deleted: boolean; previous?: WordPressUser }>;
   getCurrentUser(): Promise<WordPressUser>;
 
   // Comments
   getComments(params?: CommentQueryParams): Promise<WordPressComment[]>;
-  getComment(
-    id: number,
-    context?: "view" | "embed" | "edit",
-  ): Promise<WordPressComment>;
+  getComment(id: number, context?: "view" | "embed" | "edit"): Promise<WordPressComment>;
   createComment(data: CreateCommentRequest): Promise<WordPressComment>;
   updateComment(data: UpdateCommentRequest): Promise<WordPressComment>;
-  deleteComment(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressComment }>;
+  deleteComment(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressComment }>;
   approveComment(id: number): Promise<WordPressComment>;
   rejectComment(id: number): Promise<WordPressComment>;
   spamComment(id: number): Promise<WordPressComment>;
@@ -237,10 +219,7 @@ export interface IWordPressClient {
   getCategory(id: number): Promise<WordPressCategory>;
   createCategory(data: CreateCategoryRequest): Promise<WordPressCategory>;
   updateCategory(data: UpdateCategoryRequest): Promise<WordPressCategory>;
-  deleteCategory(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressCategory }>;
+  deleteCategory(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressCategory }>;
 
   getTags(params?: {
     search?: string;
@@ -255,62 +234,26 @@ export interface IWordPressClient {
   getTag(id: number): Promise<WordPressTag>;
   createTag(data: CreateTagRequest): Promise<WordPressTag>;
   updateTag(data: UpdateTagRequest): Promise<WordPressTag>;
-  deleteTag(
-    id: number,
-    force?: boolean,
-  ): Promise<{ deleted: boolean; previous?: WordPressTag }>;
+  deleteTag(id: number, force?: boolean): Promise<{ deleted: boolean; previous?: WordPressTag }>;
 
   // Site Management
   getSiteSettings(): Promise<WordPressSiteSettings>;
-  updateSiteSettings(
-    settings: Partial<WordPressSiteSettings>,
-  ): Promise<WordPressSiteSettings>;
-  getSiteInfo(): Promise<{
-    name: string;
-    description: string;
-    url: string;
-    home: string;
-    gmt_offset: number;
-    timezone_string: string;
-    namespaces: string[];
-    authentication: Record<string, any>;
-    routes: Record<string, any>;
-  }>;
+  updateSiteSettings(settings: Partial<WordPressSiteSettings>): Promise<WordPressSiteSettings>;
+  getSiteInfo(): Promise<import("./wordpress.js").WordPressSiteInfo>;
 
   // Application Passwords
-  getApplicationPasswords(
-    userId?: number | "me",
-  ): Promise<WordPressApplicationPassword[]>;
-  createApplicationPassword(
-    userId: number | "me",
-    name: string,
-    appId?: string,
-  ): Promise<WordPressApplicationPassword>;
-  deleteApplicationPassword(
-    userId: number | "me",
-    uuid: string,
-  ): Promise<{ deleted: boolean }>;
+  getApplicationPasswords(userId?: number | "me"): Promise<WordPressApplicationPassword[]>;
+  createApplicationPassword(userId: number | "me", name: string, appId?: string): Promise<WordPressApplicationPassword>;
+  deleteApplicationPassword(userId: number | "me", uuid: string): Promise<{ deleted: boolean }>;
 
   // Search
-  search(
-    query: string,
-    types?: string[],
-    subtype?: string,
-  ): Promise<
-    Array<{
-      id: number;
-      title: string;
-      url: string;
-      type: string;
-      subtype: string;
-    }>
-  >;
+  search(query: string, types?: string[], subtype?: string): Promise<import("./wordpress.js").WordPressSearchResult[]>;
 
   // Utility Methods
   ping(): Promise<boolean>;
-  getServerInfo(): Promise<Record<string, any>>;
+  getServerInfo(): Promise<Record<string, unknown>>;
   validateEndpoint(endpoint: string): boolean;
-  buildUrl(endpoint: string, params?: Record<string, any>): string;
+  buildUrl(endpoint: string, params?: Record<string, unknown>): string;
 }
 
 // Authentication Provider Interface
@@ -326,9 +269,9 @@ export interface IAuthProvider {
 export class WordPressAPIError extends Error {
   public readonly statusCode?: number;
   public readonly code?: string;
-  public data?: any;
+  public data?: unknown;
 
-  constructor(message: string, statusCode?: number, code?: string, data?: any) {
+  constructor(message: string, statusCode?: number, code?: string, data?: unknown) {
     super(message);
     this.name = "WordPressAPIError";
     if (statusCode !== undefined) this.statusCode = statusCode;
@@ -362,41 +305,74 @@ export class ValidationError extends WordPressAPIError {
 }
 
 // Type Guards
-export function isWordPressAPIError(error: any): error is WordPressAPIError {
+export function isWordPressAPIError(error: unknown): error is WordPressAPIError {
   return error instanceof WordPressAPIError;
 }
 
-export function isAuthenticationError(
-  error: any,
-): error is AuthenticationError {
+export function isAuthenticationError(error: unknown): error is AuthenticationError {
   return error instanceof AuthenticationError;
 }
 
-export function isRateLimitError(error: any): error is RateLimitError {
+export function isRateLimitError(error: unknown): error is RateLimitError {
   return error instanceof RateLimitError;
 }
 
-export function isValidationError(error: any): error is ValidationError {
+export function isValidationError(error: unknown): error is ValidationError {
   return error instanceof ValidationError;
 }
 
 // Response Type Guards
-export function isWordPressPost(obj: any): obj is WordPressPost {
-  return obj && typeof obj.id === "number" && obj.type === "post";
+export function isWordPressPost(obj: unknown): obj is WordPressPost {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "id" in obj &&
+    "type" in obj &&
+    typeof (obj as Record<string, unknown>).id === "number" &&
+    (obj as Record<string, unknown>).type === "post"
+  );
 }
 
-export function isWordPressPage(obj: any): obj is WordPressPage {
-  return obj && typeof obj.id === "number" && obj.type === "page";
+export function isWordPressPage(obj: unknown): obj is WordPressPage {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "id" in obj &&
+    "type" in obj &&
+    typeof (obj as Record<string, unknown>).id === "number" &&
+    (obj as Record<string, unknown>).type === "page"
+  );
 }
 
-export function isWordPressMedia(obj: any): obj is WordPressMedia {
-  return obj && typeof obj.id === "number" && obj.media_type;
+export function isWordPressMedia(obj: unknown): obj is WordPressMedia {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "id" in obj &&
+    "media_type" in obj &&
+    typeof (obj as Record<string, unknown>).id === "number" &&
+    Boolean((obj as Record<string, unknown>).media_type)
+  );
 }
 
-export function isWordPressUser(obj: any): obj is WordPressUser {
-  return obj && typeof obj.id === "number" && obj.username;
+export function isWordPressUser(obj: unknown): obj is WordPressUser {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "id" in obj &&
+    "username" in obj &&
+    typeof (obj as Record<string, unknown>).id === "number" &&
+    Boolean((obj as Record<string, unknown>).username)
+  );
 }
 
-export function isWordPressComment(obj: any): obj is WordPressComment {
-  return obj && typeof obj.id === "number" && typeof obj.post === "number";
+export function isWordPressComment(obj: unknown): obj is WordPressComment {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    "id" in obj &&
+    "post" in obj &&
+    typeof (obj as Record<string, unknown>).id === "number" &&
+    typeof (obj as Record<string, unknown>).post === "number"
+  );
 }

package/src/types/enhanced.ts

@@ -0,0 +1,318 @@
+/**
+ * Enhanced TypeScript Types for MCP WordPress
+ * 
+ * This file provides stronger typing, utility types, and generic constraints
+ * to improve type safety throughout the codebase.
+ */
+
+// Utility Types for Better Type Safety
+export type NonEmptyArray<T> = readonly [T, ...T[]];
+export type Nullable<T> = T | null;
+export type Optional<T> = T | undefined;
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends (infer U)[]
+    ? DeepReadonlyArray<U>
+    : T[P] extends readonly (infer U)[]
+    ? DeepReadonlyArray<U>
+    : T[P] extends object
+    ? DeepReadonly<T[P]>
+    : T[P];
+};
+
+interface DeepReadonlyArray<T> extends ReadonlyArray<DeepReadonly<T>> {}
+
+// Branded Types for Domain-Specific Values
+export type WordPressId = number & { readonly __brand: 'WordPressId' };
+export type UserId = number & { readonly __brand: 'UserId' };
+export type PostId = number & { readonly __brand: 'PostId' };
+export type MediaId = number & { readonly __brand: 'MediaId' };
+export type CommentId = number & { readonly __brand: 'CommentId' };
+export type CategoryId = number & { readonly __brand: 'CategoryId' };
+export type TagId = number & { readonly __brand: 'TagId' };
+
+// Helper functions to create branded types
+export const createWordPressId = (id: number): WordPressId => {
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(`Invalid WordPress ID: ${id}. Must be a positive integer.`);
+  }
+  return id as WordPressId;
+};
+
+export const createUserId = (id: number): UserId => id as UserId;
+export const createPostId = (id: number): PostId => id as PostId;
+export const createMediaId = (id: number): MediaId => id as MediaId;
+export const createCommentId = (id: number): CommentId => id as CommentId;
+export const createCategoryId = (id: number): CategoryId => id as CategoryId;
+export const createTagId = (id: number): TagId => id as TagId;
+
+// Strict URL type
+export type WordPressURL = string & { readonly __brand: 'WordPressURL' };
+export const createWordPressURL = (url: string): WordPressURL => {
+  try {
+    new URL(url);
+    return url as WordPressURL;
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+};
+
+// Enhanced Error Types with Better Constraints
+export interface TypedError<TCode extends string = string> extends Error {
+  readonly code: TCode;
+  readonly statusCode?: number;
+  readonly timestamp: Date;
+  readonly context?: Record<string, unknown>;
+}
+
+export interface ValidationError extends TypedError<'VALIDATION_ERROR'> {
+  readonly field: string;
+  readonly value: unknown;
+  readonly constraint: string;
+}
+
+export interface APIError extends TypedError<'API_ERROR'> {
+  readonly endpoint: string;
+  readonly method: string;
+  readonly statusCode: number;
+}
+
+// Enhanced Request/Response Types with Generic Constraints
+export interface BaseRequest {
+  readonly timestamp: Date;
+  readonly requestId: string;
+}
+
+export interface BaseResponse<TData = unknown> {
+  readonly success: boolean;
+  readonly data?: TData;
+  readonly error?: string;
+  readonly timestamp: Date;
+  readonly requestId: string;
+}
+
+export interface PaginatedResponse<TData> extends BaseResponse<TData[]> {
+  readonly pagination: {
+    readonly page: number;
+    readonly perPage: number;
+    readonly total: number;
+    readonly totalPages: number;
+  };
+}
+
+// Enhanced API Client Types
+export interface RequestConfig {
+  readonly timeout?: number;
+  readonly retries?: number;
+  readonly headers?: DeepReadonly<Record<string, string>>;
+  readonly signal?: AbortSignal;
+}
+
+export interface HTTPRequestOptions extends RequestConfig {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  readonly url: WordPressURL;
+  readonly data?: unknown;
+  readonly params?: DeepReadonly<Record<string, string | number | boolean>>;
+}
+
+// Tool Handler Types with Enhanced Constraints
+export interface ToolContext {
+  readonly toolName: string;
+  readonly executionId: string;
+  readonly startTime: Date;
+  readonly user?: {
+    readonly id: UserId;
+    readonly roles: NonEmptyArray<string>;
+  };
+}
+
+export interface ToolResult<TData = unknown> {
+  readonly success: boolean;
+  readonly data?: TData;
+  readonly error?: string;
+  readonly executionTime: number;
+  readonly warnings?: readonly string[];
+}
+
+export type ToolHandler<TInput, TOutput> = (
+  input: DeepReadonly<TInput>,
+  context: DeepReadonly<ToolContext>
+) => Promise<ToolResult<TOutput>>;
+
+// Cache Types with Enhanced Type Safety
+export interface CacheKey {
+  readonly namespace: string;
+  readonly operation: string;
+  readonly params: DeepReadonly<Record<string, string | number | boolean>>;
+}
+
+export interface CacheEntry<TData> {
+  readonly key: string;
+  readonly data: TData;
+  readonly createdAt: Date;
+  readonly expiresAt: Date;
+  readonly hits: number;
+}
+
+export interface CacheOptions {
+  readonly ttl: number;
+  readonly tags?: readonly string[];
+  readonly priority?: 'low' | 'medium' | 'high';
+}
+
+// Configuration Types with Better Validation
+export interface StrictSiteConfig {
+  readonly id: string;
+  readonly name: string;
+  readonly url: WordPressURL;
+  readonly auth: DeepReadonly<{
+    readonly method: 'app-password' | 'jwt' | 'basic' | 'api-key';
+    readonly username: string;
+    readonly password: string;
+  }>;
+  readonly timeout?: number;
+  readonly rateLimit?: DeepReadonly<{
+    readonly requestsPerMinute: number;
+    readonly burstLimit: number;
+  }>;
+}
+
+// Performance Monitoring Types
+export interface PerformanceMetrics {
+  readonly requestCount: number;
+  readonly averageResponseTime: number;
+  readonly errorRate: number;
+  readonly cacheHitRate: number;
+  readonly lastUpdated: Date;
+}
+
+export interface PerformanceThresholds {
+  readonly maxResponseTime: number;
+  readonly maxErrorRate: number;
+  readonly minCacheHitRate: number;
+}
+
+// Type Guards for Runtime Validation
+export const isWordPressId = (value: unknown): value is WordPressId => {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0;
+};
+
+export const isNonEmptyArray = <T>(value: unknown): value is NonEmptyArray<T> => {
+  return Array.isArray(value) && value.length > 0;
+};
+
+export const isValidURL = (value: unknown): value is WordPressURL => {
+  if (typeof value !== 'string') return false;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Conditional Types for Enhanced API
+export type RequiredFields<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// JSON Schema Type Definitions
+export interface JSONSchemaDefinition {
+  readonly type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null';
+  readonly description?: string;
+  readonly required?: boolean;
+  readonly enum?: readonly (string | number)[];
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly format?: 'email' | 'uri' | 'date-time' | 'date' | 'time';
+  readonly items?: JSONSchemaDefinition;
+  readonly properties?: DeepReadonly<Record<string, JSONSchemaDefinition>>;
+}
+
+// Enhanced MCP Tool Schema
+export interface StrictMCPToolSchema {
+  readonly type: 'object';
+  readonly properties: DeepReadonly<Record<string, JSONSchemaDefinition>>;
+  readonly required: readonly string[];
+  readonly additionalProperties: false;
+}
+
+// Result Types for Better Error Handling
+export type Result<TSuccess, TError = Error> = 
+  | { readonly success: true; readonly data: TSuccess }
+  | { readonly success: false; readonly error: TError };
+
+export const createSuccess = <T>(data: T): Result<T> => ({ success: true, data });
+export const createError = <T>(error: Error): Result<T> => ({ success: false, error });
+
+// Async Result Type
+export type AsyncResult<T, E = Error> = Promise<Result<T, E>>;
+
+// Database Types with Enhanced Constraints
+export interface DatabaseEntity {
+  readonly id: WordPressId;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly version: number;
+}
+
+export interface AuditableEntity extends DatabaseEntity {
+  readonly createdBy: UserId;
+  readonly updatedBy: UserId;
+}
+
+// Validation Result Types
+export interface ValidationResult<T> {
+  readonly success: boolean;
+  readonly data?: T;
+  readonly errors: readonly ValidationError[];
+  readonly warnings: readonly string[];
+}
+
+export type Validator<T> = (value: unknown) => ValidationResult<T>;
+
+// Enhanced Event Types for Monitoring
+export interface DomainEvent<TType extends string = string, TPayload = unknown> {
+  readonly type: TType;
+  readonly payload: TPayload;
+  readonly timestamp: Date;
+  readonly source: string;
+  readonly correlationId: string;
+}
+
+export type EventHandler<TEvent extends DomainEvent> = (event: TEvent) => Promise<void>;
+
+// Configuration Validation Types
+export interface ConfigValidationRule<T> {
+  readonly key: keyof T;
+  readonly required: boolean;
+  readonly validator: (value: unknown) => boolean;
+  readonly errorMessage: string;
+}
+
+export interface ConfigValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+// Performance Monitoring Event Types
+export type PerformanceEventType = 
+  | 'request_started'
+  | 'request_completed' 
+  | 'request_failed'
+  | 'cache_hit'
+  | 'cache_miss'
+  | 'auth_success'
+  | 'auth_failure';
+
+export interface PerformanceEvent extends DomainEvent<PerformanceEventType> {
+  readonly payload: {
+    readonly duration?: number;
+    readonly endpoint?: string;
+    readonly statusCode?: number;
+    readonly cacheKey?: string;
+    readonly userId?: UserId;
+  };
+}