/**
 * S3 client types.
 */

import type { z } from "zod";

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

/**
 * S3 action types (used internally by the client).
 */
export type S3Action =
  | "LIST_OBJECTS"
  | "LIST_BUCKET_OBJECTS"
  | "GET_OBJECT"
  | "DELETE_OBJECT"
  | "UPLOAD_OBJECT"
  | "LIST_BUCKETS"
  | "UPLOAD_MULTIPLE_OBJECTS"
  | "GENERATE_PRESIGNED_URL";

/**
 * Options for listing objects in a bucket.
 */
export interface S3ListObjectsOptions {
  /** Prefix filter for listing */
  prefix?: string;
  /** Delimiter for listing (e.g., '/' for directory-like grouping) */
  delimiter?: string;
}

/**
 * Options for getting an object.
 */
export interface S3GetObjectOptions {
  /** Response type (e.g., 'text', 'binary', 'json') */
  responseType?: string;
}

/**
 * S3 client for storage operations.
 *
 * Provides per-operation methods for common S3 tasks with schema validation.
 *
 * @example
 * ```typescript
 * const s3 = ctx.integrations.storage;
 *
 * // List buckets
 * const buckets = await s3.listBuckets(z.array(z.object({ Name: z.string() })));
 *
 * // List objects in a bucket
 * const files = await s3.listObjects('my-bucket', z.array(z.object({
 *   Key: z.string(),
 *   Size: z.number(),
 * })), { prefix: 'uploads/' });
 *
 * // Get an object
 * const content = await s3.getObject('my-bucket', 'data/file.txt', z.string());
 *
 * // Upload an object
 * await s3.uploadObject('my-bucket', 'data/file.txt', 'Hello, World!');
 *
 * // Delete an object
 * await s3.deleteObject('my-bucket', 'data/file.txt');
 *
 * // Generate a presigned URL
 * const url = await s3.generatePresignedUrl('my-bucket', 'data/file.txt', z.string());
 * ```
 */
export interface S3Client extends BaseIntegrationClient {
  /**
   * List all S3 buckets.
   *
   * @param schema - Zod schema for validating the result
   * @returns The validated bucket list
   */
  listBuckets<T>(schema: z.ZodSchema<T>, metadata?: TraceMetadata): Promise<T>;

  /**
   * List objects in a bucket.
   *
   * @param bucket - Bucket name
   * @param schema - Zod schema for validating the result
   * @param options - Optional prefix and delimiter filters
   * @param metadata - Optional trace metadata for diagnostics
   * @returns The validated object list
   */
  listObjects<T>(
    bucket: string,
    schema: z.ZodSchema<T>,
    options?: S3ListObjectsOptions,
    metadata?: TraceMetadata,
  ): Promise<T>;

  /**
   * Get an object from a bucket.
   *
   * @param bucket - Bucket name
   * @param path - Object key/path
   * @param schema - Zod schema for validating the result
   * @param options - Optional response type
   * @param metadata - Optional trace metadata for diagnostics
   * @returns The validated object content
   */
  getObject<T>(
    bucket: string,
    path: string,
    schema: z.ZodSchema<T>,
    options?: S3GetObjectOptions,
    metadata?: TraceMetadata,
  ): Promise<T>;

  /**
   * Delete an object from a bucket.
   *
   * @param bucket - Bucket name
   * @param path - Object key/path
   * @param metadata - Optional trace metadata for diagnostics
   */
  deleteObject(
    bucket: string,
    path: string,
    metadata?: TraceMetadata,
  ): Promise<void>;

  /**
   * Upload an object to a bucket.
   *
   * @param bucket - Bucket name
   * @param path - Object key/path
   * @param body - String content stored verbatim (no base64 decoding is performed).
   *   Suitable for plain text, JSON, or CSV. For binary files (PDF, DOCX, images),
   *   use {@link S3Client.uploadMultipleObjects | uploadMultipleObjects} with file references instead.
   * @param metadata - Optional trace metadata for diagnostics
   */
  uploadObject(
    bucket: string,
    path: string,
    body: string,
    metadata?: TraceMetadata,
  ): Promise<void>;

  /**
   * Upload multiple objects to a bucket.
   *
   * @param bucket - Bucket name
   * @param fileObjects - Serialized file objects
   * @param metadata - Optional trace metadata for diagnostics
   */
  uploadMultipleObjects(
    bucket: string,
    fileObjects: string,
    metadata?: TraceMetadata,
  ): Promise<void>;

  /**
   * Generate a presigned URL for an object.
   *
   * @param bucket - Bucket name
   * @param path - Object key/path
   * @param schema - Zod schema for validating the result
   * @param metadata - Optional trace metadata for diagnostics
   * @returns The validated presigned URL
   */
  generatePresignedUrl<T>(
    bucket: string,
    path: string,
    schema: z.ZodSchema<T>,
    metadata?: TraceMetadata,
  ): Promise<T>;
}