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

import type { z } from "zod";

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

/**
 * Client for executing OracleDB queries with type-safe validation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { oracledb: oracledb(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.oracledb
 *
 * // Query with validation
 * const UserSchema = z.object({
 *   id: z.number(),
 *   name: z.string(),
 *   email: z.string().email(),
 * });
 *
 * const users = await oracledb.query(
 *   'SELECT * FROM users WHERE status = :1',
 *   UserSchema,
 *   ['active']
 * );
 * ```
 */
export interface OracleDBClient extends BaseIntegrationClient {
  /**
   * Execute a SQL query and validate results against a Zod schema.
   *
   * @param sql - SQL query string (use :1, :2, etc. 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
   */
  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 }>;
}