/**
 * Databricks integration client types.
 *
 * Provides typed methods for executing Databricks queries with runtime validation.
 */

import type { z } from "zod";

import type { BaseIntegrationClient } from "../../types.js";
import type { TraceMetadata } from "../registry.js";

/**
 * Client for executing Databricks queries with type-safe validation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { databricks: databricks(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.databricks
 *
 * // Query with validation
 * const DataSchema = z.object({
 *   id: z.number(),
 *   value: z.string(),
 *   timestamp: z.string(),
 * });
 *
 * const data = await databricks.query(
 *   'SELECT * FROM data WHERE date = :PARAM_1',
 *   DataSchema,
 *   ['2024-01-01']
 * );
 * ```
 */
export interface DatabricksClient extends BaseIntegrationClient {
  /**
   * Execute a SQL query and validate results against a Zod schema.
   *
   * @param sql - SQL query string (use :PARAM_1, :PARAM_2, etc. for parameters)
   * @param schema - Zod schema to validate the query results
   * @param params - Optional query parameters, bound positionally so the first value maps to :PARAM_1
   * @returns Promise resolving to validated query results
   *
   * @throws {QueryValidationError} If results don't match schema
   * @throws {IntegrationError} If query execution fails
   */
  query<T>(
    sql: string,
    schema: z.ZodSchema<T>,
    params?: unknown[],
    metadata?: TraceMetadata,
  ): Promise<T[]>;

  /**
   * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.
   *
   * @param sql - The SQL statement to execute
   * @param params - Optional parameters for prepared statements
   * @returns Promise resolving to execution result with row count
   */
  execute(
    sql: string,
    params?: unknown[],
    metadata?: TraceMetadata,
  ): Promise<{ rowCount: number }>;
}