import type { SharedV3ProviderMetadata } from "@ai-sdk/provider"

/**
Extracts provider-specific metadata from API responses.
Used to standardize metadata handling across different LLM providers while allowing
provider-specific metadata to be captured.
*/
export type MetadataExtractor = {
  /**
   * Extracts provider metadata from a complete, non-streaming response.
   *
   * @param parsedBody - The parsed response JSON body from the provider's API.
   *
   * @returns Provider-specific metadata or undefined if no metadata is available.
   *          The metadata should be under a key indicating the provider id.
   */
  extractMetadata: ({ parsedBody }: { parsedBody: unknown }) => Promise<SharedV3ProviderMetadata | undefined>

  /**
   * Creates an extractor for handling streaming responses. The returned object provides
   * methods to process individual chunks and build the final metadata from the accumulated
   * stream data.
   *
   * @returns An object with methods to process chunks and build metadata from a stream
   */
  createStreamExtractor: () => {
    /**
     * Process an individual chunk from the stream. Called for each chunk in the response stream
     * to accumulate metadata throughout the streaming process.
     *
     * @param parsedChunk - The parsed JSON response chunk from the provider's API
     */
    processChunk(parsedChunk: unknown): void

    /**
     * Builds the metadata object after all chunks have been processed.
     * Called at the end of the stream to generate the complete provider metadata.
     *
     * @returns Provider-specific metadata or undefined if no metadata is available.
     *          The metadata should be under a key indicating the provider id.
     */
    buildMetadata(): SharedV3ProviderMetadata | undefined
  }
}
