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

import type { z } from "zod";

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

/**
 * Client for executing BigQuery queries with type-safe validation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { bigquery: bigquery(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.bigquery
 *
 * // Query with validation
 * const EventSchema = z.object({
 *   event_id: z.string(),
 *   event_name: z.string(),
 *   timestamp: z.string(),
 * });
 *
 * const events = await bigquery.query(
 *   'SELECT * FROM events WHERE date = ?',
 *   EventSchema,
 *   ['2024-01-01']
 * );
 * ```
 */
export interface BigQueryClient extends BaseIntegrationClient {
  /**
   * Execute a SQL query and validate results against a Zod schema.
   *
   * @param sql - SQL query string (use ? placeholders for parameters)
   * @param schema - Zod schema to validate the query results
   * @param params - Optional query parameters, bound positionally from the provided array
   * @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 }>;
}