/**
 * Snowflake Postgres client types.
 *
 * Snowflake Postgres is a SQL database integration that supports parameterized
 * queries via the `body` and `parameters` proto fields.
 */

import type { z } from "zod";

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

/**
 * Snowflake Postgres client for SQL query and execute operations.
 *
 * @example
 * ```typescript
 * const sfpg = ctx.integrations.db;
 *
 * // Parameterized query
 * const users = await sfpg.query(
 *   'SELECT * FROM users WHERE status = $1',
 *   UserSchema,
 *   ['active'],
 * );
 *
 * // Execute a mutation
 * const result = await sfpg.execute(
 *   'INSERT INTO users (name, email) VALUES ($1, $2)',
 *   ['Alice', 'alice@example.com'],
 * );
 * ```
 */
export interface SnowflakePostgresClient extends BaseIntegrationClient {
  /**
   * Execute a SQL query and return validated rows.
   *
   * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
   * @param schema - Zod schema for validating each result row
   * @param params - Optional query parameters for server-side binding
   * @returns Array of validated rows
   */
  query<T>(
    sql: string,
    schema: z.ZodSchema<T>,
    params?: unknown[],
    metadata?: TraceMetadata,
  ): Promise<T[]>;

  /**
   * Execute a SQL statement (INSERT, UPDATE, DELETE).
   *
   * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
   * @param params - Optional query parameters for server-side binding
   * @returns The affected row count
   */
  execute(
    sql: string,
    params?: unknown[],
    metadata?: TraceMetadata,
  ): Promise<{ rowCount: number }>;
}