/**
 * @fileoverview Base handler interfaces and types for standardized handler patterns
 * @packageDocumentation
 */

import { DeepSourceClientFactory } from '../../client/factory.js';
import { Logger } from '../../utils/logging/logger.js';
import { ApiResponse } from '../../models/common.js';

/**
 * Base dependencies that all handlers require
 */
export interface BaseHandlerDeps {
  /** Factory for creating DeepSource API clients */
  clientFactory: DeepSourceClientFactory;
  /** Logger instance for the handler */
  logger: Logger;
  /** Function to retrieve the API key */
  getApiKey: () => string;
}

/**
 * Generic handler function type
 * @template TParams - The input parameters type
 * @template TResult - The result type (defaults to ApiResponse)
 */
export type HandlerFunction<TParams = unknown, TResult = ApiResponse> = TParams extends undefined
  ? () => Promise<TResult>
  : (params: TParams) => Promise<TResult>;

/**
 * Factory function type for creating handlers with dependencies
 * @template TDeps - The dependencies type (extends BaseHandlerDeps)
 * @template TParams - The handler parameters type
 * @template TResult - The handler result type
 */
export type HandlerFactory<
  TDeps extends BaseHandlerDeps = BaseHandlerDeps,
  TParams = unknown,
  TResult = ApiResponse,
> = (deps: TDeps) => HandlerFunction<TParams, TResult>;

/**
 * Handler configuration for registration
 */
export interface HandlerConfig<TParams = unknown> {
  /** The name of the handler/tool */
  name: string;
  /** Factory function to create the handler */
  factory: HandlerFactory<BaseHandlerDeps, TParams>;
  /** Optional custom dependencies (will be merged with base deps) */
  customDeps?: Partial<BaseHandlerDeps>;
}

/**
 * Result type for handlers that return structured data
 */
export interface HandlerResult<T> {
  /** The structured data */
  data: T;
  /** Optional metadata about the result */
  metadata?: {
    /** Total count of items (for paginated results) */
    totalCount?: number;
    /** Whether there are more pages */
    hasMore?: boolean;
    /** Cursor for next page */
    nextCursor?: string;
  };
}

/**
 * Error result type for standardized error handling
 */
export interface HandlerError {
  /** Error code for categorization */
  code: string;
  /** Human-readable error message */
  message: string;
  /** Additional error details */
  details?: Record<string, unknown>;
  /** Suggested actions for resolution */
  suggestions?: string[];
}