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

import type { z } from "zod";

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

/**
 * Client for executing MySQL queries with type-safe validation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { mysql: mysql(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.mysql
 *
 * // Query with validation
 * const UserSchema = z.object({
 *   id: z.number(),
 *   name: z.string(),
 *   email: z.string().email(),
 * });
 *
 * const users = await mysql.query(
 *   'SELECT * FROM users WHERE status = ?',
 *   UserSchema,
 *   ['active']
 * );
 * ```
 */
export interface MySQLClient 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
   * @returns Promise resolving to validated query results
   *
   * @throws {QueryValidationError} If results don't match schema
   * @throws {IntegrationError} If query execution fails
   *
   * @example
   * ```typescript
   * const UserSchema = z.object({
   *   id: z.number(),
   *   name: z.string(),
   *   email: z.string().email(),
   * });
   *
   * const users = await mysql.query(
   *   'SELECT * FROM users WHERE status = ?',
   *   UserSchema,
   *   ['active']
   * );
   * ```
   */
  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
   *
   * @example
   * ```typescript
   * const result = await mysql.execute(
   *   'UPDATE users SET last_login = NOW() WHERE id = ?',
   *   [userId]
   * );
   * console.log(`Updated ${result.rowCount} rows`);
   * ```
   */
  execute(
    sql: string,
    params?: unknown[],
    metadata?: TraceMetadata,
  ): Promise<{ rowCount: number }>;
}