/**
 * GCS (Google Cloud Storage) client types.
 */

import type { z } from "zod";

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

/**
 * GCS action types (used internally by the client).
 */
export type GCSAction =
  | "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 GCSListObjectsOptions {
  /** Prefix filter for listing */
  prefix?: string;
}

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

/**
 * GCS client for storage operations.
 *
 * Provides per-operation methods for common GCS tasks with schema validation.
 *
 * @example
 * ```typescript
 * const gcs = ctx.integrations.storage;
 *
 * // List buckets
 * const buckets = await gcs.listBuckets(z.array(z.object({ name: z.string() })));
 *
 * // List objects in a bucket
 * const files = await gcs.listObjects('my-bucket', z.array(z.object({
 *   name: z.string(),
 *   size: z.string(),
 * })), { prefix: 'uploads/' });
 *
 * // Get an object
 * const content = await gcs.getObject('my-bucket', 'data/file.txt', z.string());
 *
 * // Upload an object
 * await gcs.uploadObject('my-bucket', 'data/file.txt', 'Hello, World!');
 *
 * // Delete an object
 * await gcs.deleteObject('my-bucket', 'data/file.txt');
 *
 * // Generate a signed URL
 * const url = await gcs.generateSignedUrl('my-bucket', 'data/file.txt', z.string());
 * ```
 */
export interface GCSClient extends BaseIntegrationClient {
  /**
   * List all GCS 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 filter
   * @param metadata - Optional trace metadata for diagnostics
   * @returns The validated object list
   */
  listObjects<T>(
    bucket: string,
    schema: z.ZodSchema<T>,
    options?: GCSListObjectsOptions,
    metadata?: TraceMetadata,
  ): Promise<T>;

  /**
   * Get an object from a bucket.
   *
   * @param bucket - Bucket name
   * @param path - Object 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?: GCSGetObjectOptions,
    metadata?: TraceMetadata,
  ): Promise<T>;

  /**
   * Delete an object from a bucket.
   *
   * @param bucket - Bucket name
   * @param path - Object 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 path
   * @param body - File content (base64 or text)
   * @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 signed URL for an object.
   *
   * @param bucket - Bucket name
   * @param path - Object path
   * @param schema - Zod schema for validating the result
   * @param metadata - Optional trace metadata for diagnostics
   * @returns The validated signed URL
   */
  generateSignedUrl<T>(
    bucket: string,
    path: string,
    schema: z.ZodSchema<T>,
    metadata?: TraceMetadata,
  ): Promise<T>;
}