/**
 * Google Sheets client types.
 */

import type { z } from "zod";

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

/**
 * Google Sheets action types.
 */
export type GoogleSheetsAction =
  | "READ_SPREADSHEET"
  | "READ_SPREADSHEET_RANGE"
  | "APPEND_SPREADSHEET"
  | "CREATE_SPREADSHEET_ROWS"
  | "CLEAR_SPREADSHEET"
  | "CREATE_WORKSHEET";

/**
 * Parameters for Google Sheets operations.
 */
export interface GoogleSheetsParams {
  /** Spreadsheet ID */
  spreadsheetId: string;
  /** Sheet title/name */
  sheetTitle?: string;
  /** Range in A1 notation (e.g., "A1:D10") */
  range?: string;
  /** Row number for single row operations */
  rowNumber?: string;
  /** Whether to extract first row as header */
  extractFirstRowHeader?: boolean;
  /** Header row number */
  headerRowNumber?: string;
  /** Data format */
  format?: string;
  /** Data to write (JSON string) */
  data?: string;
  /** Whether to preserve header row when clearing */
  preserveHeaderRow?: boolean;
  /** Whether to include header row in output */
  includeHeaderRow?: boolean;
  /** Destination type for writes */
  writeToDestinationType?: string;
  /** Body content */
  body?: string;
  /** New sheet configuration for CREATE_WORKSHEET action */
  addSheet?: {
    sheetTitle: string;
    rowCount?: string;
    columnCount?: string;
  };
}

/**
 * Google Sheets client for spreadsheet operations.
 *
 * Provides a generic run() method for executing Google Sheets operations.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { sheets: gsheets(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.sheets
 *
 * // Read a range
 * const RowSchema = z.array(z.object({
 *   name: z.string(),
 *   email: z.string(),
 * }));
 *
 * const data = await ctx.integrations.sheets.run('READ_SPREADSHEET_RANGE', RowSchema, {
 *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
 *   sheetTitle: 'Sheet1',
 *   range: 'A1:B10',
 *   extractFirstRowHeader: true,
 * });
 *
 * // Append rows
 * await ctx.integrations.sheets.run('APPEND_SPREADSHEET', z.any(), {
 *   spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
 *   sheetTitle: 'Sheet1',
 *   data: JSON.stringify([{ name: 'John', email: 'john@example.com' }]),
 * });
 * ```
 */
export interface GoogleSheetsClient extends BaseIntegrationClient {
  /**
   * Execute a Google Sheets operation.
   *
   * @param action - The operation to perform
   * @param schema - Zod schema for validating the result
   * @param params - Operation parameters
   * @returns The validated result
   */
  run<T>(
    action: GoogleSheetsAction,
    schema: z.ZodSchema<T>,
    params: GoogleSheetsParams,
    metadata?: TraceMetadata,
  ): Promise<T>;
}