import type { CapturedLog, RequestFormat } from "../schemas";

/**
 * Provider Protocol Interface
 *
 * Defines the contract that all providers must implement to support
 * different LLM APIs (Anthropic, OpenAI, etc.).
 */
export type ProviderProtocol = {
  /** Provider identifier (e.g., "anthropic", "openai") */
  name: string;

  /**
   * Check if this provider handles the given model.
   * @param model - Model name from request
   * @returns true if this provider should handle the model
   */
  matches(model: string): boolean;

  /**
   * Get the upstream base URL for this provider.
   * @param isChatCompletions - Whether the request uses OpenAI chat completions format
   * @param providerConfig - Optional provider configuration for custom base URL
   * @returns Upstream base URL
   */
  getUpstreamBase(isChatCompletions: boolean, providerConfig?: { baseUrl?: string }): string;

  /**
   * Extract structured response from streaming data.
   * @param raw - Raw SSE stream data
   * @param log - Captured log entry to update
   * @param fallbackModel - Fallback model name if not in stream
   * @param collectChunks - Whether to collect SSE chunks into log.streamingChunks
   * @returns JSON string of structured response
   */
  extractStream(
    raw: string,
    log: CapturedLog,
    fallbackModel?: string,
    collectChunks?: boolean,
  ): string;

  /**
   * Optional request transformation hook.
   * @param body - Original request body
   * @param apiFormat - Request format (anthropic/openai/unknown)
   * @returns Transformed body or null to use original
   */
  transformRequest?(body: string, apiFormat: RequestFormat): string | null;
};
