/**
 * MongoDB client types.
 */

import type { z } from "zod";

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

/**
 * MongoDB operation types.
 */
export type MongoDBAction =
  | "aggregate"
  | "count"
  | "deleteOne"
  | "deleteMany"
  | "distinct"
  | "find"
  | "findOne"
  | "insertOne"
  | "insertMany"
  | "listCollections"
  | "replaceOne"
  | "updateOne"
  | "updateMany";

/**
 * Parameters for MongoDB operations.
 */
export interface MongoDBParams {
  /** Filter/query object */
  query?: Record<string, unknown>;
  /** Filter object (alias for query) */
  filter?: Record<string, unknown>;
  /** Document to insert or replacement document */
  document?: Record<string, unknown>;
  /** Update operations */
  update?: Record<string, unknown>;
  /** Aggregation pipeline */
  pipeline?: Record<string, unknown>[];
  /** Fields to project */
  projection?: Record<string, unknown>;
  /** Sort specification */
  sort?: Record<string, unknown>;
  /** Maximum documents to return */
  limit?: number;
  /** Documents to skip */
  skip?: number;
  /** Field for distinct operation */
  field?: string;
  /** Additional options */
  options?: Record<string, unknown>;
}

/**
 * MongoDB client for database operations.
 *
 * Provides a generic run() method for executing any MongoDB operation.
 *
 * @example
 * ```typescript
 * // Declare in api(): integrations: { mongodb: mongodb(INTEGRATION_ID) }
 * // In run(), access via ctx.integrations.mongodb
 *
 * const UserSchema = z.object({
 *   _id: z.string(),
 *   name: z.string(),
 *   email: z.string(),
 * });
 *
 * // Find documents
 * const users = await mongodb.run(
 *   'users',
 *   'find',
 *   UserSchema,
 *   { query: { active: true }, limit: 10 }
 * );
 *
 * // Insert a document
 * const result = await mongodb.run(
 *   'users',
 *   'insertOne',
 *   z.object({ insertedId: z.string() }),
 *   { document: { name: 'John', email: 'john@example.com' } }
 * );
 * ```
 */
export interface MongoDBClient extends BaseIntegrationClient {
  /**
   * Execute a MongoDB operation.
   *
   * @param collection - Collection name (use empty string for listCollections)
   * @param action - The operation to perform
   * @param schema - Zod schema for validating the result
   * @param params - Operation parameters
   * @returns The validated result
   */
  run<T>(
    collection: string,
    action: MongoDBAction,
    schema: z.ZodSchema<T>,
    params?: MongoDBParams,
    metadata?: TraceMetadata,
  ): Promise<T>;
}