import type { ExecutionContext } from '../../base/types'

/**
 * Base integration adapter interface
 * All integration adapters must implement this interface
 *
 * Integration adapters provide a standardized way to call external REST APIs
 * with proper credential validation and error handling.
 *
 * @example
 * ```typescript
 * class GmailAdapter implements BaseIntegrationAdapter {
 *   readonly name = 'gmail'
 *
 *   async call(method: string, params: unknown, credentials: Record<string, unknown>, context?: ExecutionContext) {
 *     // Implementation
 *   }
 *
 *   validateCredentials(credentials: Record<string, unknown>): boolean {
 *     // Validation logic
 *   }
 * }
 * ```
 */
export interface BaseIntegrationAdapter {
  /** Integration name (e.g., 'gmail', 'slack') */
  readonly name: string

  /**
   * Call integration method
   * @param method - Method name (e.g., 'sendEmail', 'postMessage')
   * @param params - Method parameters
   * @param credentials - Organization credentials for this integration
   * @param context - Execution context for logging and tracing
   * @returns Method result
   */
  call(
    method: string,
    params: unknown,
    credentials: Record<string, unknown>,
    context?: ExecutionContext
  ): Promise<unknown>

  /**
   * Validate credentials for this integration
   * @param credentials - Credentials to validate
   * @returns true if valid, false otherwise
   */
  validateCredentials(credentials: Record<string, unknown>): boolean
}
